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PREFACE 


Manual Objectives 


After reading this manual, you will be able to use the command 
language and utilities included in the PRO/Tool Kit. 


This book does not describe how to use the Professional computer, 
nor does it describe how to write applications. For information 
on using the Professional, including installing your application, 
see the Professional 300 Series User’s Guide for Hard Disk 
System. For information on writing applications, see the Tool 
Kit User’s Guide. For information on the base system software 
Supporting the Professional 300 Series computer, see the P/OS 
System Reference Manual. 


Intended Audience 


Readers who already know a command language will benefit most 
from this manual. You should have a working knowledge of the 
application development cycle as described in the Tool Kit User’s 
Guide. 


Structure of This Document 
This manual consists of the following chapters: 


e Chapter 1 introduces the PRO/Tool Kit Digital Command 
Language (DCL), the PRO/Tool Kit Monitor Console Routine 
(MCR), which is a terminal interface to the P/OS, and 
PRO/Tool Kit Utilities. 


@® Chapter 2 describes the structure of the DCL command line, 
operation of the DCL Single Line Editor (SLE), how to use 
P/OS file specifications, and the foreground and _ background 
processing feature of P/OS. 


e Chapter 3 lists the PRO/Tool Kit DCL commands alphabetically, 
and includes a description and syntax for each command. 


@® Chapter 4 details the Indirect Command Processor, which 
processes command files. 


XV 


Chapter 5 describes how to customize PRO/DCL command 
processing. 


Chapter 6 describes the File Compare (CMP) utility, which 
compares the contents of two ASCII files. 


Chapter 7 explains the File Dump (DMP) utility, which allows 
you to examine the contents of a file or volume of files. 


Chapter 8 describes the Librarian (LBR) utility, which allows 
you to create, update, modify, list, and maintain library 
files. 


Chapter 9 describes the Resource Monitoring Display (RMD), 
which allows you to display information about the resources 
in your system. 


Chapter 10 describes the Task/File Patch Program (ZAP), which 
allows you to directly examine and modify task image and data 
files. 


Chapter 11 describes the Source Language Input Program (SLP), 
a utility that you can use to maintain and audit source 


files. 


Chapter 12 shows you how to convert numbers among different 
radixes using the Convert Utility (CVT). 


Chapter 13 tells you how to perform file control operations 
using the Peripheral Interchange Program (PIP). 


Chapter 14 describes how to update, or patch, code in a 
relocatable binary object module using the Object Module 
Patch UtL1ity (PAT); 


Chapter 15 tells you how to use the File structure 
Verification Utility (VFY), which allows you to check the 
readability and validity in files, directories, and volumes. 


Appendix A contains functions initiated by DCL commands. 


Appendix B lists the common error messages for PRO/Tool Kit 
DCL and the utilities. 


Appendix C contains an EDT command file example. 
Appendix D describes the structure of the MCR command line 


and lists the PRO/Tool Kit MCR commands alphabetically, 
including a description and syntax for each command. 
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Associated Documents 


PRO/Tool Kit Installation Guide and Release Notes 

For directions on installing the PRO/Tool Kit, as well as 
information specific to the current version of the PRO/Tool 
Kit, read this document. 


Professional 300 Series User’s Guide for Hard Disk System 


You should read this manual if you are not familiar with the 
Professional computer. 


Tool Kit User’s Guide 

This manual details the program development cycle, and 
provides primary information on devices, volumes, and file 
specifications. 

P/OS System Reference Manual 

This manual explains P/OS concepts and describes system 


services, callable routines and directives, system I/0 
capabilities and the I/O drivers. 


Conventions Used in This Document 


Convention/Term Meaning 
[optional ] In a command line, square brackets indicate that 
the enclosed item is optional. In a file 


specification, however, square brackets are part 
of the required syntax. 


UPPERCASE Uppercase words and letters indicate that you 


should type the word or letter exactly as shown. 


lowercase Lowercase words and letters indicate that you 


should substitute a word or value of your own. 
Usually the lowercase word identifies the type 
of substitution required. 
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Convention/Term 


[s] or [,8] 


<CR> 
<CTRL/x> 


red 


BOLD 
Tool Kit 
Host Tool Kit 


PRO/Tool Kit 


Meaning 


If you can repeat an item in a command line, [s] 
appears after the item to show its plural form. 
A comma or other punctuation preceding the 
letter "s" indicates that you must separate 
repeated items with that punctuation. 


A vertical ellipsis means that not all the 
statements are shown. 


This manual sometimes shows carriage returns, 
represented by <CR>, to delineate an example 
Clearly. 


This notation indicates that you are to press 
the key marked "Ctrl" while Simultaneously 
pressing another key on the keyboard. 


Interactive input appears in red. 


In command syntax, the bold portion indicates 
the minimally acceptable abbreviation for the 
command. 


This general term refers to the software you use 
to develop applications to run on a Professional 
computer. 


The Host Tool Kit is Tool Kit software that runs 
on a host computer, rather than on the 
Professional itself. 


The PRO/Tool Kit is the Tool Kit software that 
runs on the Professional computer. 
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CHAPTER 1 
INTRODUCTION 


The PRO/Tool Kit is an application that allows you to develop 
programs on the Professional computer. It includes two command 
languages, PRO/Tool Kit DCL and PRO/Tool Kit MCR, as well as 
several utility programs that help you with the development 
process. This chapter introduces PRO/Tool Kit DCL, PRO/Tool Kit 
MCR, and the PRO/Tool Kit utilities. For information on hardware 
and software requirements and for installation instructions, see 
the PRO/Tool Kit Installation Guide and Release Notes. 


1.1 PRO/TOOL KIT DCL 


The PRO/Tool Kit DCL is a subset of Digital Command Language 
implementations found on the VAX/VMS and RSX-11M-PLUS operating 
systems. Although some commands are unique to the PRO/Tool Kit, 
many of the commands derive from both of these operating systems. 


PRO/Tool Kit DCL provides you with an extensive set of commands 
to perform various functions. You can divide the PRO/Tool Kit 
DCL commands into five groups: 


File Manipulation 
Program Development 
Task Manipulation 
Set and Show 
Miscellaneous 


The following sections describe the commands in each functional 
group. Chapter 3 presents the commands in alphabetical order. 
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1.1.1. File/Device/Volume Manipulation Commands 


The file manipulation commands are: 


ANALYZE/MEDIA DUMP 
APPEND EDIT 

ASSIGN EDIT/PROSE 
CONVERT EDIT/SLP 
COPY FORMAT 
CREATE/DIR INITIALIZE 
DIRECTORY MOUNT 
DEASSIGN PRINT 

DEFINE PRINT/REMOTE 
DELETE PURGE 
DELETE/DIRECTORY RENAME 
DIFFERENCES SUBMIT/REMOTE 
DIRECTORY TYPE 
DISMOUNT UNLOCK 


1.1.2 Program Development Commands 


The program development commands are: 


BASIC LIBRARY/INSERT 
COBOL LIBRARY/LIST 
DEBUG LIBRARY/REMOVE 
DIBOL LIBRARY/REPLACE 
FORTRAN LINK 

LIBRARY LINK/C81 
LIBRARY/COMPRESS LOAD 
LIBRARY/CREATE MACRO 
LIBRARY/DELETE PASCAL 
LIBRARY/EXTRACT UNLOAD 


1.1.3. Task Manipulation Commands 


The task-related commands are: 


ABORT REMOVE 

ASSIGN/TASK RUN installed task 

CANCEL RUN uninstalled task 

CONTINUE SPAWN 

FIX START 

INSTALL START /UNBLOCK 
STOP/BLOCK 
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1.1.4 Set and Show Commands 
The set and show commands are: 


SET [DAY]TIME 

SET DEFAULT 

SET DEVICE 

SET FILE 

SET HOST 

SET PRIORITY 

SET PROMPT 

SET PROTECTION 

SET PROTECTION/DEFAULT 
SET PROTECTION/NODEFAULT 
SET TERMINAL 

SHOW ASSIGNMENTS 

SHOW CLOCK_QUEUE 

SHOW COMMON 


1.1.5 Miscellaneous Commands 


The miscellaneous commands are: 


BROADCAST 
CLEAR 
EXIT 

HELP 

MAIL 
PHONE 
REPLY 


1.2 PRO/TOOL KIT MCR 


The PRO/Tool Kit MCR is a subset of the Monitor 
found on RSX-11M-PLUS operating systems. 
between 


as a terminal interface 


Operating System. 


SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 


you 


[DAY ]TIME 

DEFAULT 

DEVICES 

LOGICALS 

MEMORY | 

PROTECTION 

TASKS /ACTIVE 
TASKS/INSTALLED 
TASKS/DYNAMIC 

TASK: taskname/DYNAMIC 
TASKS /ACTIVE/DYNAMIC 
TASK/LOGICAL UNITS 
TERMINAL 

USERS 


There are two ways to enter MCR commands: 


@e You can explicitly enter the command by prefixing it 


MCR. 


the 
the 


@ You can define 
equate it to 


command at the DCL $ prompt. 
PRO/DCL by 


customize 


logical 
value of MCR. 


name 


DCL$COMMAND_OPTIONS 


You can then enter an MCR 
Chapter 5 
defining 


describes 
the logical 


Console Routine 
PRO/Tool Kit MCR serves 
and the Professional 


how 
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DCLSCOMMAND_OPTIONS. Appendix D describes the MCR commands. 


1.3  PRO/TOOL KIT UTILITIES 
The PRO/Too1. Kit. utilities comprise the. following: 
e The Compare Utility (CMP) 
e The EDT, PROSE, and SLP editors 
@® Frame Development Tool (FDT) 
@e The PRO/FMS-11 Forms Editor (PROFED) 
@e The PRO/FMS-11 Forms Utility (PROFUT) 
e The Librarian Utility (LBR) 
@e The Resource Monitoring Display (RMD) 
@ Various RMS utilities 
e The Task/File Patch Program (ZAP) 
e The Convert Utility (CVT) 
e The Peripheral Interchange Processor (PIP) 
e The Object Module Patch Utility (PAT) 
e The Verify Utility (VFY) 
You can invoke most of these utilities through a corresponding 
DCL command. Those utilities that you cannot call through DCL 


must be invoked directly. Refer to the specific utility below 
for instructions. 


1.3.1 Program Development, Frame, and Form Utilities 
These utilities allow users to perform the following functions: 


e Edit text files using a text editor (such as EDT) 
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Develop menus with the Frame Development Tool (FDT) 


Assemble MACRO-11 source files with the Professional MACRO-11 
Assembler (PMA) | 


Build applications with the Professional Application Builder 
(PAB) 


Invoke the Record Management Services 


You should refer to the corresponding Tool Kit Documentation for 


a complete description and operating instructions for these 
utilities. 
® Text Editors 
To invoke EDT, the DIGITAL standard text editor, use _ the 
commands EDIT, EDIT/EDT, or the following command: 
S RUN SEDT 
If you prefer, you can use the PROSE editor instead of EDT. 
To invoke PROSE, use the command EDIT/PROSE. In addition, 
the SLP editor is available; to invoke SLP, use the command 
EDIT/SLP or the command RUN SSLP. 
® FDT (Frame Development Tool) 
FDT creates interactive menus for P/OS applications. The 
following command invokes this utility: 
S RUN SFDT 
For complete details on FDT, see the Tool Kit Reference 
Manual. 
@® PROFED (PRO/FMS-11 Forms Editor) 


PROFED is an editor that lets you create and modify video 
forms on the screen. The use of the PRO/FMS-11 Forms utility 
(PROFUT) translates these forms into files for use by an 
application program. The following command invokes this 
ULLLECYy: 


S RUN S$PROFED 


See the FMS-11/RSX Software Reference Manual for details on 
uSing PROFED. 
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@ PROFUT (PRO/FMS-11 Forms Utility) 


PROFUT creates form description files that are the output 
from the PRO/FMS-11 forms editor. An application program can 
display these files. The following command invokes’ this 
UtCLLICys 


S RUN SPROFUT 


See the FMS-11/RSX Software Reference Manual for details on 
uSing PROFUT. 


@e PAB (Professional Application Builder) 


The Professional Application Builder links one or more object 
modules into an executable task image, which is the final 
form of any application or system program. PAB resolves 
addressing and overlay considerations. To invoke PAB in DCL, 
use the LINK command or the command RUN SPAB. 


PAB is based on the RSX-11M/M-PLUS Task Builder. Refer to 
the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for 
additional information on PAB. 


@e PMA (Professional MACRO-11 Assembler) 
PMA assembles and lists MACRO-11 source files. The MACRO 
command, or the command RUN SPMA, invokes this utility. 


Refer to Chapter 3 and the PDP-11 MACRO-11 Language Reference 
Manual for further details on the MACRO-11 assembler). 


1.3.2 RMS Utilities 
The PRO/Tool Kit contains the utilities listed in this section. 
NOTE 
Refer to the RSX-11M/M-PLUS RMS-11 Utilities 
Manual for a description of the RMS utilities. 


Only those RMS utilities listed below are 
Supported on the PRO/Tool Kit. 


® RMSCNV 
RMSCNV is the RMS-11 file conversion utility that moves 


records between two RMS-11 files of any organization or 
record format. You can invoke RMSCNV by typing the 
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following: 

S RUN SRMSCNV 
You can also use the DCL command CONVERT. 
RMSDES 


RMSDES allows you to design and create indexed, sequential, 
and relative files. You can specify the file attributes 
interactively or read in the attributes of an existing, 
external data file that you want to re-create with little or 
no modification. You can invoke RMSDES by typing the 
Following: 


S RUN SRMSDES 
There 1s no other DCL command to invoke RSMDES. 
RMSDSP 


RMSDSP lists RMS-11 file attributes and structural data. You 
invoke this utility by typing the following: 


S RUN $RMSDSP 
You can also use the DCL command DIRECTORY/ATTRIBUTES. 
RMSIFL 
RMSIFL indexed file load utility builds an indexed file using 
records from another RMS-11 file of any organization type. 
This utility uses techniques that are derived from the basic 
structure of indexed files, rather than from the standard 
RMS-11 file structure. You invoke this utility by typing the 
following: 


S$ RUN SRMSIFL 


There is no other DCL command to invoke RMSIFL. 
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1.3.3 Other Utilities 


Chapters 6 through 15 fully describe the CMP, DMP, LBR, RMD, ZAP, 
SLP, CVT, PIP, PAT, and VFY utilities, respectively. The syntax 


you use to invoke these is: 
S RUN Sutility-name 


The utility then displays its prompt. 


CHAPTER 2 
USING PRO/TOOL KIT DCL 


You can use PRO/Tool Kit DCL interactively by typing a command at 
the keyboard, or you can invoke a DCL command file using the 
Indirect Command Processor (refer to Chapter 4). Whichever 
method you use, the format of the command is the same. 


You enter your commands at the DCL command level (indicated by 
the S$ prompt), and press either the <RETURN> or <DO> key to 
execute the command. Because P/OS waits for a carriage return 
before processing the DCL command, you can edit the command line 
before pressing <RETURN>. (See Section 2.2.) 


You are only required to type as many letters of the DCL command 
as needed to form a unique command. For example, the 
abbreviation SET TE/UP is a valid, unique command, because there 
are no duplications of this within the SET TERMINAL command or 
within the PRO/Tool Kit Command Language (refer to SET TERMINAL 
in Chapter 3). However, SET TE/VT would not be a unique command 
because this abbreviation could stand for either SET 
TERMINAL/VT100 or SET TERMINAL/VT125. 


2.1 THE DCL COMMAND LINE 


This section introduces the rules governing the use of DCL. The 
examples in this section are intended to illustrate these rules, 
not to document the full capabilities of the commands. For more 
detail, see the individual command descriptions in Chapter 3. 


A command consists of a command name, or verb, describing the 
action the system is to take. Most commands also include one or 
more parameters and qualifiers to further define the action of 
the command. Qualifiers are preceded by a slash (/) and 
parameters are preceded by a espace. Both qualifiers and 
parameters can take arguments. Arguments are preceded by a colon 
(:). The format of a PRO/Tool Kit DCL command is: 
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S$ Command/cmd-qual[s] param1[/param-qual ] param2[/param-qual ] 


where: 

$ indicates the DCL command level prompt. 

Command is the name of the DCL command. 

/cemd-qual is an optional command qualifier that directs 
the command either to perform or omit auxiliary 
functions. 

paraml is a parameter that you pass to the command for 
processing (not required by all commands). 

param-qual is an optional parameter qualifier that causes 
the DCL command to perform or omit auxiliary 
functions on the parameter. 

param2 is a second parameter that you pass to the DCL 
command for processing (not required by all 
commands). 


Either the <RETURN> or <DO> key is the terminator that passes DCL 
commands to the operating system. Unless the action of the 
<RETURN> key differs greatly from what is expected, the command 
examples and formats in this manual do not include an indication 
that each command line is terminated by a carriage return. (See 
Section 2.1.6 for a discussion of command lines that are too long 
to fit on one line of your terminal.) 


Some commands require parameters or arguments as part of the 
command line. If you fail to supply a required command element, 
DCL prompts you with one or two words indicating the general 
nature of the required element. If you do not understand the 
prompt, type a question mark (?) for help. (In some cases, an 
omission causes an error rather than a prompt.) 


2.1.1. Prompting 


The prompts help you learn the form of a command by requesting 
that you supply required command elements. 


For example, the RENAME command works as follows: 
S RENAME 


From? FILEL.LIS 
TO? FILE2.MAC 
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The one-line format for RENAME is: 
S RENAME FILE1.LIS FILE2.MAC 


The formats can be mixed. DCL prompts for whatever you leave 


out. For example: 


S RENAME FILE1.LIS 
To? FILE2.MAC 


There are no defaults for prompts. You must supply a response to 
any prompt. If you do not want to continue with the command, 
type a CTRL/Z. 


2.1.2 Qualifiers 


Qualifiers modify the action of the command. Qualifiers always 
start with a slash (/) and are generally optional. 


Qualifiers are either command qualifiers or parameter qualifiers. 
Most qualifiers are command qualifiers. In this manual, command 
qualifiers are always shown immediately following the command 
verb, as in this example: 

S TYPE/TODAY *.HLP 


However, most command qualifiers can appear anywhere in_ the 
command line. Another name for these qualifiers is floating 
qualifiers. The following examples illustrate how command 
qualifiers can float: 

S TYPE *,.HLP/TODAY 


or 


S$ TYPE 
File(s)? *.HLP/TODAY 


or 
S$ TYPE 
File(s)? /TODAY 
File(s)? *.HLP 


You can mix formats, as in the following example: 


S TYPE/TODAY 
File(s)? *.HLP/EXCLUDE:HELPF.HLP;* 
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or 


$ TYPE/TODAY 
File(s)? *.HLP/ 
Qualifier? EXCLUDE:HELPF.HLP;* 


or 


$ TYPE/TODAY 

File(s)? / 

Qualifier? EXCLUDE:HELPF.HLP;* 
File(s)? *.HLP 


Note that you are prompted for a qualifier when a slash with no 
qualifier attached appears on the command line. When you supply 
the qualifier, do not type the slash again. 


Regardless of where the qualifier appears, it has the same 
effect. 


Qualifiers described as parameter qualifiers, Or Filespec 
qualifiers, cannot float. 


Parameter qualifiers do not modify the action of the command; 
they modify the action of the command as it concerns that 
particular parameter, or supply additional information needed for 
the command to execute properly. For instance, in the following 
example: 


S MACRO HIYA, TESTBLD/LIBRARY, PIGEON 


the qualifier /LIBRARY identifies a particular file as being a 
library, and the /LIBRARY qualifier cannot float. 


Many qualifiers can be negated by prefixing NO or - (minus) to 
the qualifier name. Thus, the command: 


S MACRO/OBJECT SIMPLE.MAC 


directs the MACRO-11 Assembler to make an object file, while the 
command: 


S MACRO/NOOBJECT SIMPLE.MAC 
or 
S MACRO/-OBJECT SIMPLE.MAC 
directs the MACRO-11 Assembler to omit the object file. In the 


first example, /OBJECT is the default qualifier and need not be 
explicitly included. In other words, unless your MACRO command 
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includes the /NOOBJECT qualifier, an object file is produced. 


2.1.3 HELP 


HELP is available for all DCL commands by entering the HELP 
command or by typing a question mark (?) in response to any DCL 
prompt. For instance, if you want help on the TYPE command, 
enter the following: 


S HELP TYPE 
The following HELP text is displayed: 


TYPE[/qualifier[s]] filespec[,s] 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 
/EXCLUDE: filespec 
/NOWARNINGS 
/ SHARED 


With PRO/DECNET extensions, the following qualifiers are 


also 

available: 
/ LOG 
/MACY11 


The TYPE command displays the contents of text files on your 
terminal. 


Abbreviation: T 


If you wish help on one of the qualifiers for TYPE, enter’ the 
following: 


S HELP TYPE TODAY 
TYPE/TODAY filespec([s] 


The /TODAY qualifier specifies that you wish the TYPE 
command to type only files created today. 


The HELP text consists of a brief explanation of the command 


followed by an illustration of the syntax, showing that TYPE 
accepts one or more filespecs, and one or more qualifiers. 
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If you wish help while being prompted by the TYPE command, use 
the following procedure: 


S TYPE 

File(s)? ? 

TYPE{/qualifier[s]] filespec[s] 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 
/EXCLUDE: filespec 


The TYPE command displays the contents of text files on your 
terminal. 


File(s)? 
The same help text is printed on your terminal, but the prompt 
returns, meaning the TYPE command is still waiting for you to 
list the file(s) you wish typed. 
You can also get help on a specific subtopic while being prompted 
by a command, by responding to the prompt with a question mark. 
For example: 

S$ SET 

Function? 2 


Sel. thing 


The SET command can be used to set’ something. The 
following things can be set with this command: 


[DAY ]TIME DEFAULT DEVICE FILE HOST 
PRIORITY PROMPT PROTECTION TERMINAL 
To get help on a specific subtopic of the SET command, enter a 
question mark followed by the subtopic: 
Function? ? DEFAULT 
SET DEFAULT [ddnn:][directory] 


The SET DEFAULT command sets your default directory or 
device, or both. 


Function? 
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You can also get help by typing a question mark in response _ to 
the DCL prompt (S$). 


If you should decide after reading the help text that you have 
chosen the wrong command, enter a <CTRL/Z> in response to the 
prompt to end the execution of the command. (A <CTRL/Z> in 
response to a prompt always cancels execution of the current DCL 
command. ) 


2.1.4 Abbreviations 


It is rarely necessary for you to type either the complete 
command name or the complete qualifier name. You only need to 
type the characters required to distinguish the command or 
qualifier from all others. 


For example: 


@® TYPE can be abbreviated as T because it is the only command 
beginning with that character. 


@ DELETE can be abbreviated as DEL, but not DE. 

@ DEASSIGN can be abbreviated as DEA, but not DE. 
Three letters is usually enough. Five letters is always enough. 
You can often omit other parts of commands as well. 
The underscore character (_) is used to make DCL commands more 
readable where two words are needed to name a single command 
element, such as EDIT/READ_ONLY. However, you need not type the 
underscore to enter the command. EDIT/READ_ONLY is the same as 


EDIT/READONLY. 


Here are the brief forms for some frequently used commands. 


A for ABORT C for COPY D for DIRECTORY 
DEA for DEASSIGN E for EDIT F for FORTRAN 

H for HELP L for LINK M for MACRO 

R for RUN S for SHOW T for TYPE 


The command descriptions in Chapter 3 indicate the minimum 
acceptable abbreviation for each command. 
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2.1.5 Colon and Equal Sign 

The command descriptions in this manual show arguments set off by 
a. colon: “(2). You can always replace such colons with an equal 
Sign (=), as in this example: 


$ DIFFERENCES/LINES=2 testfile.tmp 


Refer to Section 3.22 for a description of the DIFFERENCES 
command. Colons in device names, such as DWi:, and so forth, 
cannot be replaced by equal signs. 


2.1.6 Command Line Continuation 


The hyphen (-) is used to indicate line continuation. When you 
end a command line with a hyphen and a carriage return, the DCL 
continuation prompt (S-) indicates that you can continue entering 
the command line. If you are continuing a line from a prompt, 
such as: 

Task? 


that prompt is the indication that the line is being continued. 
This feature permits you to enter command lines including more 
characters than your terminal has room for on one line. No DCL 
command line can be longer than 250 characters. Here is an 
example of line continuation: 


S$ COPY PROCOM1.PAS, PROCOM2.PAS,PROCOM3.PAS,-<CR> 
$- BIGFILE.PAS [WORK] 


The command is not entered until DCL encounters a line ending 
with a carriage return not preceded by a hyphen. In the example, 
the first carriage return does not enter the command because it 
is preceded by a hyphen. The command is entered following the 
second carriage return. The carriage return can be on a line by 
itself. 


2.1.7 Comments in Command Lines 


You can include comments in a DCL command line using the 
exclamation point (!). 


If the comment ends the command line, only a single exclamation 
point is needed, as in this example: 


S COPY PROCOM1.PAS PROCOM1.TMP ! Temporary file 
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If the comment is within the command line, two exclamation points 
are needed, as in this example: 


S COPY !Temporary File! PROCOM1.PAS PROCOM1.TMP 
These comments are ignored and not interpreted in any way by DCL. 


Comments can be placed at any natural break in the command line: 
between qualifiers, between parameters, even as part of a 
response to a prompt. 


2.1.8 Errors 


You can correct typing errors or delete the line completely by 
using the <DELETE> key, or <CTRL/U> (provided you have not 
terminated the line). 


You can cancel the execution of any DCL command by typing a 
<CTRL/Z>. 


If the system detects an error in the command line input, it 
returns the appropriate error message. 


Here are some examples of incorrect commands and the error 
messages they produce: 


S KOPY PRO300.LIS PRINT.LIS 
DCL -- Illegal command 


S RENAME/COPY TEST.PAS PROCOM1.PAS 
RENAME -- Illegal or contradictory qualifier 
RENAME/COPY TEST.PAS PROCOM1.PAS 


S DIFFERENCES/LINES=TWO TEST.PAS PROCOM1.PAS 
DIFFERENCES -- Numeral expected 
DIFFERENCES/LINES=TWO TEST.PAS PROCOM1.PAS 


In the first case, the error was detected by DCL, as indicated by 
the first part of the error message. There is no DCL KOPY 
command. The entire command was rejected. 


In the second case, the command was entered correctly, but the 
qualifier was incorrect. The first part of the message shows 
that the error was detected within the RENAME command itself. 
The command is reprinted and a circumflex (*) points to the 
error. 
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In the third case, the command and qualifier were correct, but 
the argument was inerror. The message explains the error and 
the circumflex points to the error. 


Sometimes the circumflex does not point directly at the error, 
but at the point at which the command started to go wrong, which 
may be several characters before the actual error. 


Typing mistakes are by far the most common cause of errors. 
Retyping the command or using the <UP ARROW> and the Single Line 
Editor (SLE) often eliminates the error. (See the discussion of 
the Single Line Editor, below.) Other common causes of errors are 
omitting a space or other delimiter in a command line, specifying 
invalid devices or nonexistent files, and failing to type a 
sufficient number of characters to distinguish the command or 
command element. 


All the DCL error messages are listed and explained in Appendix B 
of this manual. In some cases, such as assembly errors, you may 
need to go to another manual for explanation of the error. 


2.1.9 PRO/Tool Kit DCL Initialization and Termination Files 


When you enter the PRO/Tool Kit, two indirect command files 
automatically execute. Similarly, two indirect command files 
automatically execute when you leave the PRO/Tool Kit. These 
initialization and termination files install and remove tasks 
that you need for developing applications on the Professional. 


The initalization files execute in the following order when you 
enter the PRO/Tool Kit: 


1. LB:[ZZPRODCL]START.CMD 


This is the first command file to execute. It executes 
automatically for all users of the PRO/Tool Kit. Commands 
that should always be executed during PRO/Tool Kit 
initialization are located in this file. Only a system 
manager should modify this file. For example, if all 
PRO/Tool Kit users on a system require a particular library, 
the system manager could modify LB:[ZZPRODCL]START.CMD- to 
install that library. 


2. DCLAPPLSDIR:START.CMD 
This command file is located in a user-specific area, 
DCLAPPLSDIR, and so it can be different for each user. For 


instance, if you are the only user who needs a certain 
library installed, you can modify DCLAPPLSDIR:START.CMD to 


2210 


see 
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perform the installation during your PRO/Tool Kit session. 
Alternatively, you might place the comment character before 
lines that install tasks you do not use. 


termination command files execute in the following order when 
leave the PRO/Tool Kit: 

LB: [ZZPRODCL]EXIT.CMD 

This command file is provided so that you can specify 
commands to be executed ona system-wide basis during DCL 
termination. The termination file corresponds to the 
initialization file LB:[ZZPRODCL]START.CMD. 
DCLAPPLS$DIR:EXIT.CMD 

This command file is provided so that you can _ specify 
commands to be executed on a user-specific basis during DCL 


termination. The termination file corresponds to the 
initialization file DCLAPPLSDIR:START.CMD. 


Chapter 4 for information on indirect command files. 


CORRECTING MISTAKES WITH THE DCL SINGLE LINE EDITOR 


This is a brief description of how the Single Line Editor works. 


The 


Single Line Editor can be used in two ways: 


If you make a mistake before you press either <RETURN> or 
<DO>, you can correct it without retyping the entire command. 
To correct the command, press the <LEFT ARROW> key until the 
cursor is just to the right of any character(s) you want to 
change. Delete the part you do not want with the <X] key and 
retype. To adda part you left out, move the cursor to the 
place and type in the omitted part. The rest of the command 
will move to the right to make room. 


If you make a mistake after you have pressed either <RETURN> 
or <DO>, press the <UP ARROW> key. The command will be 
redisplayed for changing. You can display up to nine 
previous commands this way. You can then use the <DOWN 
ARROW> key to display the next command. 


While entering DCL commands, the <CANCEL> key erases’ the 


current command so you can start over. The <F13> function 
key erases from where the cursor is to the end of the line. 


2-11 


CORRECTING MISTAKES WITH THE DCL SINGLE LINE EDITOR 


Normal text characters simply get entered into the command line 
at the position of the cursor. If there are any characters on, 
or to the right of the cursor, they will move to the right to 
make room for the new character. 


The following list describes what keys on the keyboard perform 
what functions in the single line editor. 


<X ] 


<REMOVE> 


<RETURN> 
<DO> 


<LEFT ARROW> 
<RIGHT ARROW) 


<UP ARROW> 


<DOWN ARROW> 


<F13> 


<EXITD 


<HELP> 


<CTRL/E> 


Erases the character to the left of the cursor. 
If there are any characters on, or to the right 
of the cursor, they will move to the left to 
close the space for the erased character. 


Erases the character on the cursor. If there 
are any characters to the right of the cursor, 
they will move to the left to close the space 
for the erased character. 


Enters the current command, giving it to the 
DCL command interpreter for execution. After 
the command has executed, the line following 
the one that was just entered (if there is one) 
will be displayed, with the cursor at the end 
of the line. To execute it, press <RETURN> or 
<DO>. To skip over it, press the down arrow. 


Moves the cursor one column to the left or to 
the right. 


Stores the current command, and displays the 
previous command, leaving the cursor at the 
end. If there is no previous command, no action 
is taken. 


Stores the current command, and displays the 
next command. If there are no more commands, 
then just start an empty line. 


Erases the command from the cursor position to 
the end of the line. 


Leaves the PRO/Tool Kit and returns to the P/OS 
Main Menu. 


Inserts "HELP" at the beginning of the current 
command, and enters it. 


Places the cursor at the end of the command 
line. 


CORRECTING MISTAKES WITH THE DCL SINGLE LINE EDITOR 


<CTRL/H> Places the cursor at the beginning of the 
command line. 

<CANCEL> Erases the entire current command, and starts 

<CTRL/U> with a blank command. 

<CTRL/C> 

<CTRL/R> Redisplays the current command. 

<CTRL/W> 


2.3 P/OS FILE SPECIFICATIONS IN DCL 


File specifications, often called filespecs, are required for 
many DCL commands. The format of a file specification is as 
follows: 


nodespec: :device:[directory]filename.type;version 


Note that the nodespec portion of a file specification is valid 
only on those commands supported by PRO/DECnet, as indicated in 
the command descriptions in Chapter 3. Your Professional must 
have PRO/DECnet installed in order to use the nodespec to operate 
on files at other nodes on the network. 


See the Tool Kit User’s Guide for a complete description of file 
Specifications. 


2.3.1 Wildcard Features in DCL 


PRO/Tool Kit DCL offers wildcard features that are in addition to 
the simple wildcard capability available throughout P/OS (see the 
Tool Kit User’s Guide). In the simple form of wildcarding, you 
use the * to replace an entire field in a filespec. 


Many commands described in this manual work through PIP, the 
Peripheral Interchange Program. For the PIP-related 
commands--DIRECTORY, DELETE, PURGE, COPY, RENAME, TYPE, APPEND, 
UNLOCK, and SET PROTECTION--a more elaborate form of wildcarding 
is available. In these commands, within filenames and file 
types, the * can be used in a more complex manner. The * 
actually means "match zero or all characters in this position." 


Therefore, the command: 


S DIRECTORY L*.TXT 


P/OS FILE SPECIFICATIONS IN DCL 


lists the most recent versions of all files with the type .TXT 
whose names start with L on the default volume and in the default 
directory. 
And the command: 

S DIRECTORY *L*.TXT 
lists the most recent versions of all files with the type .TXT 
whose names include an L on the default volume and in the default 


directory. 


The same substitutions can also be used in file types, so that 
the command: 


S$ DIRECTORY SNOBLO.L* 
lists the most recent versions of all files with the name SNOBLO 
and the type beginning with an L on the default volume and in the 
default directory. 
You can use more than one wildcard in filenames and file types. 
The command: 


S DIRECTORY *F*D*. TXT 


lists the most recent versions of all files with the type .TXT 
whose names include an F and aD in that order. 


In addition, the PIP-related commands permit the percent sign (%) 
to be used as a wildcard, but only within filenames and file 


types. The % means "match exactly one character in this 
position." 


For instance, the following command: 
S$ DIRECTORY %.TXT 


lists all files with the type .TXT and ae single-character 
filename on the default volume in the default directory. 


The command: 
$ DIRECTORY NOV%%81.TXT 
lists all files with the type .TXT and a filename consisting of 


NOV and 81 separated by two characters on the default volume in 
the default directory. | 


P/OS FILE SPECIFICATIONS IN DCL 


The wildcards can be combined in a single filespec. 
The command 
S DIRECTORY %L*T.TM% 


lists all files whose names begin with a single character 
followed by an L and end with a T, and with a file type 
consisting of .TM and another single character on the default 
volume in the default directory. 


Wildcarding, combined with systematic usage of directory 
Structure, filenames, and file types, can add considerable 
flexibility and convenience to your use of the system. 


2.3.2 Logical Name Translation 


You can specify a logical name to stand for either a part or 
whole file specification. For example, you can define the 
logical name INPUT to have an equivalence consisting of the file 
specification BIGVOLUME:[USERFILES]NAMES.TXT. Subsequently, you 
can use INPUT wherever you would normally use the file 
Specification. See the Tool Kit User’s Guide for more 
information on logical names. 


Note that PRO/Tool Kit commands translate logical names only when 
a device, directory, or file specification is expected. 


2.4 FOREGROUND AND BACKGROUND PROCESSING 


Once you initiate a command, you cannot type another command 
until the first command has completed execution. In this case, 
you initiated the command in foreground mode. Typing <CTRL/C> or 
<INTERRUPT/DO> halts the execution of a command or program in 
foreground mode. 


You can initiate commands or programs in background mode through 
the use of the SPAWN command. Once you have initiated such a 
command or program, you can issue other commands or run programs 
at your terminal; you need not wait for the background command or 
program to complete execution. In order to halt the execution of 
a command or program running in background mode, you must use the 
ABORT commmand. 


FOREGROUND AND BACKGROUND PROCESSING 


2.4.1 <CTRL/C> 


<CTRL/C> or the <INTERRUPT/DO> key sequence aborts the command 
you just typed at the terminal. <CTRL/C> cancels command entry 
Or processing, and interrupts command or program execution, 
returning control to DCL. However, <CTRL/C> will not abort a 
commmand or program that you initiated with the SPAWN command. 
You must use ABORT to halt the execution of such a command or 
program. 


For example, if you just typed DIRECTORY and realized you did not 
want to execute the DIRECTORY command, use of <CTRL/C> will abort 
the action of the DIRECTORY command. 


2.4.2 ABORT 


This command halts execution of commands and programs running in 
background mode. 


NOTE 


If you use SPAWN to initiate a DCL command in 
background mode, that DCL command runs as a task 
with a task name of the form xxxTn, where xxx are 
the first three characters of the DCL command, 
and Tn is the name of the terminal from which the 
command was issued. 


To determine the name of the task running in background mode, use 
the SHOW TASKS command. 


NOTE 


You should never initiate a command or. program 
that attaches the terminal in background mode, 
because you cannot abort it. 


CHAPTER 3 
DCL COMMANDS 


This chapter lists the PRO/Tool Kit DCL commands alphabetically 
and provides description, syntax, options, and command prompts 
for each command. Note that in the syntax description of each 
command, the portion of the command shown in bold indicates the 
minimally acceptable abbreviation. 


Some of the PRO/Tool Kit DCL commands can be used for network 
operations, or have qualifiers that enable network operations. 
In order to use these commands and qualifiers for network 
operations, you must first install the PRO/DECnet Tool Kit. When 
you install the PRO/DECnet Tool Kit, the DCL extensions are also 
automatically installed. See the PRO/DECnet Installation Guide 
for details. 


ABORT 


3.1 ABORT 


ABORT forces an orderly end to a running task or to the action of 
a specfic command. Nonprivileged users can abort any task 
running on TI:. Privileged users can abort any task. 


Syntax 
ABORT [/COMMAND] [/qualifier] commandname 
ABORT/TASK [/qualifier] taskname 
qualifier 
/ COMMAND 
/TASK 
/TERMINAL: ttnnn: 
commandname 
Specifies the command whose effect you want to cancel. This 
parameter can be used only when the /TASK qualifier is not 


present. You must specify at least the first three 
characters of the command verb. 


taskname 
Specifies the name of the task you want to abort. This 
parameter requires the presence of the /TASK qualifier. If 


you use the /TASK qualifier and do not specify a task name, 
you will get the error message "Illegal task name." 


Command Qualifiers 


/COMMAND 


Specifies that you want to abort a command. This is the 
default qualifier and need not be specified. 


/TASK 


Specifies by name the task that you want to abort. 


ABORT 


/TERMINAL: ttnnn: 
Specifies that a task from some terminal other than your own 
be aborted. This is a privileged qualifier. 
Example 
S SPAWN LINK filespec 
S$ ABORT LINK 
In this example, the user issued a LINK command in the background 
by using the SPAWN ' command. The user then entered the ABORT 
command to terminate the command before it finished. 
S SPAWN LINK filespec 
S$ ABORT/TASK LINT1 
In this example, the user issued a LINK command in the background 
by using the SPAWN command. The user then entered the ABORT 


command and specified the name of the task that the SPAWN LINK 
command executed to terminate the task build. 


ANALYZE/MEDIA 
3.2  ANALYZE/MEDIA 


ANALYZE/MEDIA allows you to identify and determine the number of 
bad blocks on a disk. This command deletes all existing files on 
a volume, determines if bad blocks exist on a disk volume, and 
records their locations for use by the INITIALIZE command. 


Syntax 
ANALYZE/MEDIA[/qualifier] device 


qualifier 


/{NO]CONFIRM 
device 


Specifies the name of the device on which the magnetic 
medium containing the volume is currently mounted. This 
argument can be of the form ddnnn:, or it can be a_ logical 
name previously assigned to the device. 


Prompt 
Device? device 

Qualifiers 

/([NO]CONFIRM 
The NOCONFIRM qualifier specifies that P/OS should not 
verify that the volume is already in FILES-11 format. The 


/CONFIRM qualifier asks you to verify the analyze request if 
the volume is already in FILES-11 format. /CONFIRM is the 


default. 


APPEND 


3.3 APPEND 


APPEND attaches records from one or more sequential files to the 
end of an existing sequential file. For details regarding 
sequential files, see the manual PRO/RMS-11: An Introduction, in 
the Tool Kit documentation set. 


Syntax 

APPEND([/qualifier[s]] infile[,s] outfile 
qualifier 

Can be one or more of the Potowine: 


/DATE: dd-mmm-yy 

/SINCE:dd-mmm-yy 

/ THROUGH :dd-mmm-yy 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 

/NOWARNINGS 

/ SHARED 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/DATA_TYPE 
JLOG 

/MACY11 

/PRINT 
/TRANSFER_MODE 
/SUBMIT 
/PROTECTION 
/OWNER 


infile 


Specifies the file or files to be appended to the output 
file. 


outfile 
Specifies the file to which the input files are appended. 


The output file must be an existing sequential file. The 
output file has the same version number after the APPEND 
command is executed as it had before the command was issued. 
The input files appear at the end of the output file in the 
order they were specified. 


APPEND 


No wildcards are permitted in the output file specification. 
There are no qualifiers for the output filespec. 


Although the output file must exist, it may be an empty 
file. 


Prompts 


File(s)? infile[,s] 
To: outfile 


Qualifiers 
/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the APPEND 
command to affect only files created by the value specified 
for /DATE. 


/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the APPEND 
command to affect only files created on or since the value 
Specified by /SINCE. 


/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the APPEND 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined _ to 
Specify that you want the APPEND command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the APPEND 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the APPEND 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 


APPEND 


/ [NO ]WARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
specified do not exist. 


/ SHARED 


The /SHARED qualifier specifies that you want other users to 
be able to access the file while you are performing the 
operation. 


Additional Qualifiers Available with PRO/DECnet 


Command Qualifiers 


/LOG 
The /LOG qualifier specifies that the names of files 
appended and their sizes in blocks are to be displayed as 
the operation is performed. 

/PRINT 
The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
file will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 

/SUBMIT 


The /SUBMIT qualifier specifies that the output file is a 
temporary file and will be submitted to the remote batch 
processor facility when copied. The file will be deleted 
after it is processed at the remote node. 


File Qualifiers 
/DATA_TYPE 


The /DATA_TYPE qualifier specifies how the data in the file 
is interpreted. /DATA_TYPE with APPEND requires either the 


ASCII or IMAGE argument. The default is IMAGE. /DATA_TYPE 
must be entered after the file specification in the command 
line. 


The ASCII argument transfers files in ASCII record mode and 
translates the records into an appropriate format for the 
remote system. You only need to use this argument when 
transferring text files to remote systems with file systems 


a) 


APPEND 


other than FILES-11 or RMS. File transfers to VAX/VMS' and 
PDP-11/RSX systems are more efficiently performed using the 
default, IMAGE. 


The IMAGE argument transfers files with their current format 
and attributes. If a remote system cannot interpret the 
file format, an error message will be displayed. If the 
file is an ASCII text file, you can recover by retrying with 
the ASCII argument. 


/MACY11 


The /MACY11 qualifier specifies that the input or output 
file on the remote TOPS-10 or TOPS-20 system is in MACY11 
format. This informs the remote DECsystem to handle the 
file appropriately when copying to or from the P/OS system. 
/MACY11 must be entered after the file specification in the 
command line. 


/TRANSFER_MODE 


The /TRANSFER_MODE qualifier specifies the method of 
packaging file data during a file transfer. This qualifier 
requires either the BLOCK or RECORD argument with the APPEND 
command. RECORD is the default. /TRANSFER_MODE must be 
entered after the file specification in the command line. 


The BLOCK argument transfers files in block mode, uSing 
blocks of 512-byte sizes. This is more efficient than using 
record mode, but should only be used with systems that 
Support FILES-11 or RMS-1i1, such as VAX/VMS, PDP-11/RSX, or 
PDP-11/RSTS/E RMS FAL. 


The RECORD argument transfers a file one record at a time. 
A record is a logical unit of data ina file. 


/OWNER 


This qualifier specifies the UIC of the file. A UIC 
establishes the owner of a file. See the Tool Kit User’s 
Guide for a description of UIC. 


/PROTECTION: code 


This qualifier specifies the protection code applied to’ the 
output file. See the description of the SET PROTECTION 
command for details on the code. 


ASSIGN 


3.4 ASSIGN 


This command creates a logical name and assigns an equivalence 
string to the specified logical name. An equivalence name can be 
a device name, another logical name, a file specification, or any 
other string. 


To specify the logical name table in which you want to enter a 
logical name, use /USER, /SESSION, or /SYSTEM. If you do not 
explicitly specify a logical name table, the default is /SESSION. 


Syntax 

ASSIGN[/qualifier[s]] equiv_name logical_name 
qualifier 

Can be one or more of the following: 


/USER 

/ SESSION 

/SYSTEM 

/FINAL 

/TRANSLATION_ ATTRIBUTES 


equiv_name 


Defines the equivalence name to be associated with the 
logical name in the specified logical name table. The 
equivalence name string can contain from i to 200 
characters. If the equivalence name contains quotation 
marks, enclose the string in quotation marks and use_ two 
sets of quotation marks ("") in the places where you want a 
quotation mark to appear. 


Note that if you enclose an equivalence name string in 
quotation marks the case of alphabetic characters is 
preserved. 


logical_name 


Specifies the logical name string. The logical name string 
Can contain from 1 to 255 characters. If the logical name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") in the places 
where you want a quotation mark to appear. 


Note that if you enclose a logical name string in quotation 
marks the case of alphabetic characters is preserved. 
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ASSIGN 


Prompts 


Equivalence Name? equiv_name 
Logical Name? logical_name 


Qualifiers 
/USER 


Places the logical name in the user logical name table. 
Logicals created in the user logical name table are deleted 
when you exit any application (including DCL). 


/ SESSION 


Places the logical name in the session logical name table. 
Session logical names are deleted when you logout of the 
system. If you do not explicitly specify a logical name 
table, the default is /SESSION. 


/ SYSTEM 


Places the logical name in the system logical name table. 
All system users can access the logical name. 


System logical names are never deleted unless an explicit 
deassign logical operation is performed. 


/ FINAL 


Indicates that the equivalence name string should not be 
translated iteratively; logical name translation should 
terminate with the current equivalence string. The /FINAL 
qualifier 1s synonymous with: 


/TRANSLATION_ATTRIBUTES: TERMINAL 
/TRANSLATION_ATTRIBUTES:[(keyword[,...])] 
Specifies one or more attributes to modify a logical name 
string. The /TRANSLATION_ATTRIBUTES qualifer is positional 


and must be specified before the equivalence name. 


You can specify the following keywords for translation 
attributes: 


ASSIGN 


CONCEALED Indicates that the logical name is a concealed 
device name. If you specified the CONCEALED 
attribute, the logical name must be a device 
name of the form ddnnn: and the equivalence 
mame must be of the form -_ddnnn:[directory.]. 
The device name in the equivalence name must be 
present. The [directory.] portion of the 
equivalence name is optional. 


TERMINAL Indicates that the equivalence name string 
Should not be translated iteratively; logical 
name translation should terminate with the 
current equivalence string. 


If you specify only one keyword, you may One the 
parentheses. Only the attributes you specify are set. 


Examples 


S ASSIGN DW001:[CHARLES] CHARLIE: 
S$ PRINT CHARLIE: TEST.DAT 


The ASSIGN command associates the logical name CHARLIE with the 


device and directory DW001:{CHARLES]. Susequent references to 
the logical name CHARLIE: result in the correspondence between 
the logical name CHARLIE: and the disk and directory specified. 
The PRINT command queues a copy of the file 


DW001:[CHARLES]TEST.DAT to the default print queue. 
S ASSIGN DW001:[CHARLES] CHARLIE: /USER 


The ASSIGN command associates the logical name CHARLIE: with the 
directory name [CHARLES] on the device DW001: and makes the 
assignment in the user logical name table. 


S AS/TRANSLATION_ATTRIBUTES:CONCEALED _DW002:[CHARLES.] - 
S-PDO0OO01: 
S$ DIRECTORY PD001:[USERFILES] 


Directory PD1:[USERFILES ] 
28-JUN-85 11:20 


TEST .DAT 4. 27-JUN-85 17:21 
Total of 4./4. blocks in1. files 


The ASSIGN command associates the logical name PDOO1: with the 
directory name [CHARLES] on the device DWO002. Subsequent 
references to the device PDOQ1: result in the device and 
directory specified as being used as the MFD for all file 
operations. 


ASSIGN 


S ASSIGN/TRANSLATION_ATTRIBUTES: TERMINAL XX001: TEMP: 


The ASSIGN command associates the logical name TEMP: with the 
device XxX001. Subsequent references to the logical TEMP: will 
result in the device xXxX001: being used without any futher 
translation attempts on the equivalence name XX001:. 


ASSIGN/TASK 


3.5 ASSIGN/TASK 


ASSIGN/TASK reassigns the logical unit numbers (LUNS) of an 
installed task from one physical device to another. This 
reassignment overrides the static LUN assignments in the task’s 
disk image file. ASSIGN/TASK cannot change the LUNs of an active 
task. 
Syntax 

ASSIGN/TASK:taskname ddnnn: lun 


taskname 


Identifies the installed task whose LUN you want to 
reassign. 


ddnnn: 


Specifies the device to which you want the LUN reassigned. 
This can be a physical device or pseudo device name. 


lun 

Specifies which LUN you want to reassign to the new device. 
Prompts 

Taskname? taskname 


Device? ddnnn: 
Logical unit? lun 


BASIC 


3.6 BASIC 


BASIC invokes the PRO/Tool Kit BASIC-PLUS-2 compiler to begin a 
BASIC session. (Refer to the BASIC on RSX-11M/M-PLUS Systems 
manual and the BASIC Reference Manual for additional 
information. ) 
Syntax 

BASIC 
Prompts 


None 


BROADCAST 


3.7 BROADCAST 


When the P/OS Broadcast application is installed on your’ system 
and the target systems, the BROADCAST command allows you to 
communicate with system users. 
Syntax 
BROADCAST[/qualifier] "message-text"” 
message-text 
Specifies the message to be displayed. When a message 
contains more than one word, enclose the message in 
quotation marks. 
qualifier 
/NODE 
Prompt 
Message? 
Qualifiers 
/NODE[=(node name[,...])] 
Sends a message to the local system only. The optional 
parameter list allows you to specify which nodes will 


receive the message. The default is to send the message _ to 
all workstations connected to the system. 


CANCEL 
3.8 CANCEL 


CANCEL eliminates entries from the clock queue. Either the RUNS 
directive or the time-based forms of the RUN command place 
entries in the clock queue. CANCEL only affects pending entries 
in the clock queue and does not affect a task that is currently 
executing. 
Syntax 

CANCEL taskname 


taskname 


Is the name of the inactive, installed task entry that is to 
be deleted from the clock queue. 


Prompts 


Taskname? taskname 


CLEAR 


3.9 CLEAR 


This 


command clears the screen and optionally resets the terminal 


subsystem to an initial state. 


Syntax 


CLEAR [/qualifier] 


qualifier 


/RESET 


Prompts 


None 


Qualifier 


/RESET 


Emits a reset-to-initial-state CRIS.) sequence, which 
initializes the Terminal Subsystem to default states and 
clears the screen. The RIS sequence is normally invoked 
whenever you power-up (boot) the Professional or reset the 
PRO/Communications terminal emulator. For further 
information, see the description of the RIS sequence in the 
Terminal Subsystem Manual. 


COBOL 


3.10 COBOL 


COBOL invokes the PRO/Tool Kit COBOL-81 compiler to compile COBOL 
language source files. 


NOTE 


Please refer to the language documentation for 
additional information. 


Syntax 

COBOL[/qualifier[s]] filespec 
qualifier 

Can be one or more of the following: 


/{NO]ANSI_FORMAT 
/( NO} CHECK! arg] 

[NO]BOUNDS 

[NO]PERFORM 

ALL 

NONE 
/CODE:[NO]CIS 
/{NO]CROSS_REFERENCE 
/{[NO]DEBUG 
/{NO]DIAGNOSTICS[:filespec] 
/(NO]LIST[:filespec] 
/NAMES : XX 
/{NO]OBJECT[:filespec] 
/{NO]OVERLAY_DESCRIPTION 
/(NO]SHOW: [NO]MAP 
/{NO]SKELETON 
/ {NO ]SUBPROGRAM 
/TEMPORARY: device 
/{NO]TRUNCATE 
/{NO]WARNINGS: [NO] INFORMATIONAL 


filespec 


Specifies the source file to be input to the COBOL-81 
compiler. 


File input to the COBOL-81 compiler must contain COBOL 
source code. File specifications must have filenames. The 
default file type is .CBL. 


COBOL 


Prompts 

File? filespec 
Qualifiers 
/(NO]ANSI_FORMAT 


The /ANSI_FORMAT qualifier specifies that the source file is 
in conventional (or ANSI) format. Conventional format has 
80-character lines with Area A beginning in character 
position 8. 


The /NOANSI_FORMAT qualifier specifies that the source file 
1S in terminal format, a DIGITAL-specified format that 
permits variable length lines with Area A beginning in 
character position 1. 


The default is /NOANSI_FORMAT. 


/{NO]CHECK[ :arg] 
[NO]BOUNDS 
[NO ]PERFORM 
ALL 
NONE 


The /CHECK and /CHECK:ALL qualifiers are equivalent--both to 
each other, and also to /CHECK:BOUNDS and /CHECK:PERFORM in 
combination. They add object code that checks the ranges of 
Subscripts, indexes, and nested PERFORM statements at run 
time. 


The /CHECK:BOUNDS qualifier compares subscript and index 
ranges at run time against the ranges defined by 
corresponding OCCURS clauses. If any range is exceeded 
during program execution, COBOL-81 issues an error message. 


The /CHECK:PERFORM qualifier determines whether or not your 
program’s PERFORM statements are nested properly (if nested 
at all). If COBOL-81 detects improper nesting during 
program execution, it issues an error message. 


The /NOCHECK and /CHECK:NONE qualifiers are equivalent--both 
to each other, and also to / CHECK: NOBOUNDS and 
/CHECK:NOPERFORM in combination. They suppress all range 
checking. 


The /CHECK:NOBOUNDS qualifier suppresses range checking only 
for subscripts and indexes. 


The /CHECK:NOPERFORM qualifier suppresses range checking 
only for nested PERFORM statements. 


The qualifiers that suppress range checking reduce task size 
and improve program performance. 


The default is /CHECK (/CHECK:ALL). 
/CODE: [NO]CIS 


The /CODE:CIS qualifier tells the compiler to use CIS 
(Commercial Instruction Set) in the object code it produces. 


NOTE 


The Professional 300 Series computers do not have 
the Commercial Instruction Set. 


The /CODE:NOCIS qualifier tells the compiler not to use CIS. 


These qualifiers override the default for your system. They 
are used to develop programs that will execute on a 
different system than the one used for program development. 
For example, if your system has CIS, you use /CODE:NOCIS to 
compile a program that will run on a system without CIS. 


/[NO]CROSS_REFERENCE 


The /CROSS_REFERENCE qualifier causes the compiler to 
produce a list file and to add two cross-reference tables to 
the end of the list file: one for data-names and one_ for 
procedure-names. In each table, the names you use in your 
COBOL program are listed alphabetically. Opposite each name 
is a list of every line number in which that name occurs. A 
"D" after a number indicates the line in which you define 
the name. An asterisk (*) after a line number indicates a 
destructive reference, such as a value assignment to a 
data-name. 


The /NOCROSS_REFERENCE qualifier suppresses production of 
the cross-reference tables. 


The default 1s /NOCROSS_REFERENCE. 

/ {NO ]DEBUG 
The /DEBUG qualifier indicates that you plan to include the 
COBOL-81 Symbolic Debugger in your task image. To support 
the Symbolic Debugger, the compiler generates symbol 


information in the object module for all data-names and 
procedure-names in your program. 
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If you include the Symbolic Debugger in your program, you 
must also use the /DEBUG qualifier to the LINK command. 


The /NODEBUG qualifier suppresses generation of symbol 
information in the object module. 


The default is /NODEBUG. 
/(NO]DIAGNOSTICS[:filespec] 


The /DIAGNOSTICS qualifier creates a diagnostics file that 
contains the compiler diagnostic summary. If you do not 
append a file specification, the diagnostics file has’ the 
same filename as your source file, and the file type .DIA. 


The /NODIAGNOSTICS qualifier suppresses the creation of a 
diagnostics file. 


The default is /NODIAGNOSTICS. 

/(NOJ]LIST[:filespec] 
The /LIST qualifier produces a list file which contains both 
the complete source code and any diagnostic messages. If 
you do not append a file specification, the list file has 
the same filename as the source file and has file type .LST. 
The /NOLIST qualifier Suppresses production of a list file. 
The default is /NOLIST. 


/ NAMES : XX 


The /NAMES:xx qualifier tells the compiler to use the_ two 
alphanumeric characters you specify as the PSECT kernel for 
your program. You use this qualifier to ensure unique 
identification for PSECT kernels when your task image uses 
both subprograms and segmentation. 


/(NOJOBJECT[:filespec] 
The /OBJECT qualifier produces an object module. If you do 
not append :filespec, the object module has the same 
filename as the source and the file type .OBJ. 
The /NOOBJECT qualifier suppresses production of an object 
module and its associated skeleton ODL file. (See the 


description of /[NO]SKELETON. ) 


The default is /OBJECT. 
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/{NO]OVERLAY_DESCRIPTION 


The /OVERLAY_DESCRIPTION qualifier produces two files_an 
indirect command file and an Overlay Descriptor Language 
file. 


The indirect command file has the same filename as the 
source and the file type .CMD. It can be input to the Task 
Builder to create the task image. 


The Overlay Descriptor Language file has the same filename 
as the source and the file type .ODL. It contains pointers 
to certain support routines that must be included in your 
task image (for example, system Support for file 
input/output). : 


If you plan to use the LINK/C81 command to task-build your 
program, do not use the /OVERLAY_DESCRIPTION qualifier 
(refer to 3.46 for a description of the LINK/C81 command). 
LINK/C81 also creates a .CMD and an .ODL file, and cannot 
reference the .CMD and .ODL files created during program 
compilation. 


The /NOOVERLAY_DESCRIPTION qualifier suppresses production 
of .CMD and .ODL files during program compilation. 


The default is /NOOVERLAY_DESCRIPTION. 


/(NO]SHOW: [NO]MAP 


The /SHOW and /SHOW:MAP qualifiers are equivalent. They 
cause the compiler to produce a list file and to append two 
offset maps to the list file. One offset map refers to the 
Data Division and one to the Procedure Division. The 
compiler provides these maps for use with ODT (the On-Line 
Debugging Tool). Consult the IAS/RSX-11 ODT Reference 
Manual for more information. 


The /NOSHOW and /SHOW:NOMAP qualifiers are equivalent. They 
Suppress production of the offset maps. 


The default is /NOSHOW (/SHOW:NOMAP). 


/{NO]SKELETON 


The /SKELETON qualifier produces a skeleton ODL file, which 
specifies the overlay structure for the object module. This 
file has the same filename as the source and the file type 
-oKL. 
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You cannot use the /SKELETON qualifier to override the 
/NOOBJECT qualifier. That is, an .SKL file cannot be 
produced when the .OBJ file is suppressed. The /NOSKELETON 
qualifier suppresses production of the .SKL file. 


You cannot use the /NOSKELETON qualifier if you plan to 
task-build your program with the LINK/C81 command. LINK/C81 
assumes the presence of the .SKL file. Although the  .SKL 
file is not strictly necessary for all programs, DIGITAL 
does not recommend that you suppress its production unless 
you are familiar with task-building alternatives to 
LINK/C81. | 


The default is /SKELETON. 
/(NO]SUBPROGRAM 


The /SUBPROGRAM qualifier tells the compiler to treat the 
source file as a subprogram. You should use this qualifier 
only if the subprogram does not use parameters from the main 
program; that is, if it does not contain the Procedure 
Division USING header. 


The /NOSUBPROGRAM qualifier tells the compiler to treat the 
source aS a main program. 


The default is /NOSUBPROGRAM. 
/TEMPORARY: device 


The /TEMPORARY qualifier tells the compiler to store the 
temporary work files it uses during program compilation on 
the device you specify. Since the default device is the 
system disk (SY:), this qualifier is useful if there is 
little system disk space available. 


/{NO]TRUNCATE 


The /TRUNCATE qualifier tells the compiler to perform 
decimal truncation on the values of COMP data items. With 
decimal truncation, the maximum value the data item can 
contain depends on the item’s PICTURE character-string. 


The /NOTRUNCATE qualifier tells the compiler to perform 
binary truncation on the values of COMP data items. With 
binary truncation, the maximum value a COMP item can contain 
depends on its storage allocation. 


The default 1S /NOTRUNCATE. 
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/{NO]WARNINGS: [NO] INFORMATIONAL 


The /WARNINGS and /WARNINGS: INFORMATIONAL qualifiers are 
equivalent. They cause the compiler to issue informational, 
warning, and fatal diagnostics. 


The /NOWARNINGS and /WARNINGS:NOINFORMATIONAL qualifiers are 
equivalent. They suppress production of informational, 
warning, and fatal diagnostics. 


The default is /WARNINGS (/WARNINGS: INFORMATIONAL). 


CONTINUE 


3.11 CONTINUE 


CONTINUE resumes execution of a previously suspended task. 
Nonprivileged users can continue tasks initiated from their own 
terminals. Privileged users can continue any suspended task. 
Syntax 

CONTINUE[ /TERMINAL: ttnnn:] taskname 
qualifier 

/TERMINAL:ttnnn; 


taskname 


The name of the task to be restarted. 


Prompts 

Taskname? taskname 
Qualifiers 
/TERMINAL: ttnnn: 


Allows you to continue a suspended task running on_= some 
other terminal. This is a privileged qualifier. 


CONVERT 


3.12 CONVERT 


CONVERT invokes the RMSCNV utility, which moves records from one 
file to another. CONVERT reads records from an input file and 
writes them to an output file. This conversion depends on _ both 
the organization (sequential, relative, or indexed) of the files, 
and qualifiers included with the CONVERT command. Refer to the 
RSX-11M/M-PLUS RMS-11 Utilities Manual for further information on 
the RMSCNV utility. 


Syntax 

CONVERT[ /qualifier[{s]] input_file output_file 
qualifier 

Can be one or more of the following: 


/{NO]APPEND 
/{NO]FIXED_CONTROL 
/(NO] IDENTIFICATION 
/ INDEXED 

SREY [3] 
/{NO]LOG_FILE[:filespec] 
/{NO]MASS_INSERT 
/MERGE 
/{NO]PAD[:[#]arg] 
/RELATIVE 
/{NO]REPLACE 
/SEQUENTIAL 
/{NO]TRUNCATE 


input_file 


Specifies the name of the file that is the source of records 
to the output file. CONVERT reads records sequentially, 
regardless of the organization of the input file. CONVERT 
accepts no wildcards. 


output_file 


Specifies the name of the file to receive records from _ the 
input. file. The default file organization for the output 
file is sequential. If the output file is not sequential, 
use the /RELATIVE or /INDEXED qualifier to indicate the 
organization. If the output file is to be sequential, 
CONVERT can create the file; it need not exist prior to your 
entering the CONVERT command. CONVERT cannot create indexed 
or relative files; these must have been created prior to 
your entering the CONVERT command. Refer to the 
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CONVERT 


RSX-11M/M-PLUS RMS-11 User’s Guide for additional 
information. The CONVERT command does not accept wildcards. 


Prompts 


Input file ? input_file 
Output file? output_file 


Qualifiers 
/{NO]APPEND 


Specifies that you want RMSCNV to append records to the end 
of an existing sequential file. If the output file is not 
sequential, RMSCNV ignores the qualifier. You cannot use 
both /APPEND and /REPLACE in the same command line. 


The default is /NOAPPEND, but the action taken depends on 
the presence of the /REPLACE qualifier in the command line. 
If you specified /REPLACE, RMSCNV performs the _ replace 
operation. If you did not specify /REPLACE, RMSCNV creates 
the next higher version of the file. 


This qualifier is the equivalent of the /AP switch in an 
RMSCNV command line. | 


/{NO]FIXED_CONTROL 


The /FIXED_CONTROL qualifier directs RMSCNV_ to handle 


variable-with-fixed-control (VFC) format records in either 
the input file or the output file. If the fixed-control 
area of the input file and the output file are the same 
size, RMSCNV performs a straightforward copy. See the 
RMS-11 documentation supplied with your system for 
information on how RMSCNV handles other combinations. Lt 


you include this qualifier and neither file specifies VFC 
records, RMSCNV terminates. 


This qualifier is the equivalent of the /WF switch in an 
RMSCNV command line. 


The default is /NOFIXED_CONTROL. This means that if one of 
the named files contains VFC records, the fixed-control area 
of each record is ignored. That is, if the input file 
includes VFC records and the output file does not, only the 
variable portion of each record is written to the output 
file. If the output file includes VFC records and the input 
file does not, data is written only into the variable 
portion of each output record. 
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/{NO] IDENTIFICATION 


Requests that RMSCNV print its current version number and 
patch level on your terminal. See the RMSCNV documentation 
for more information. 


This qualifier is the equivalent of the /ID switch in an 
RMSCNV command line. 


The default is /NOIDENTIFICATION. 
/ INDEXED 


The /INDEXED qualifier informs RMSCNV that the output is of 
indexed organization. Regardless of their organization, all 
input files are read sequentially. 


RMSCNV reads each record from the input file, then applies 
the output file’s record format, that is, key placement 
within the record, to the data. If you do not specify the 
/KEY qualifier with a value, the key of reference is the 
primary key; otherwise, it is the key you specify. 


This qualifier is the equivalent of the /FO:IDX switch in an 
RMSCNV command line. 


/KEY[:n] 


Indicates the key that establishes the order in which 
records are read sequentially from an indexed input file and 
written to the output file. mn can be from 0 through 9. The 
default is n=0 and indicates the primary key; n=1 is the 
first alternate key; n=9 is the ninth alternate key. 


This qualifier is the equivalent of the /KR qualifier in an 
RMSCNV command line. 


/([NO]LOG_FILE[:filespec] 
Directs RMSCNV to summarize processing ina log. If you do 
not include a filespec, the log appears on your terminal. 
If you name a file, that file will be created and written to 
by RMSCNV. The log includes the following elements: 


e The command string in RMSCNV format. This will not be 
the same as DCL format. 


@® Copies of all error messages produced during execution. 
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@ An indication of any duplicate-key problems. If the log 
1S appearing on the terminal, the indication consists 
only of the following message: 


SOME DUPLICATE RECORDS NOT WRITTEN 


If the log is being written to a file, RMSCNV supplies 
the indicator DUP RCD= followed by the first 72 
characters of the record that could not be written. 


This qualifier is the equivalent of the /SL qualifier in an 
RMSCNV command line. 


The default is /NOLOG_FILE, meaning that only normal error 
messages appear on your terminal. 


/{NO]MASS_INSERT 


Directs RMSCNV to activate the RMS-11 mass insert I/0 
technique and then use sequential put operations to insert 
records into the output file. 


This is the equivalent of the /MA qualifier in an RMSCNV 
command line. 


The default for nonsequential file organization is 
/NOMASS_INSERT. 


/MERGE 


Directs RMSCNV to copy records from the input file into the 
output file. Both files must be of the same organization. 


/(NO]PAD[:[#]Jarg] 
Directs RMSCNV to pad records read from the input file to 


the output file’s record length before writing them to the 
file. If you specify the qualifier without an argument, the 


pad character is null. If you do not include the number 
sign (#), the argument can be any printing ASCII character 
except: the number Sign, question mark (?), or 


commercial-at sign (@). If you include the number sign, n 
can be an octal number from 0 through 377, representing the 
full ASCII character set. This enables you to use the three 
excluded characters as pad characters by specifying 43 for 
#, 77 for ?, and 100 for @. 


Use this qualifier only when the output file specifies 
fixed-length records. 
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This qualifier is the equivalent of the /PD qualifier in an 
RMSCNV command line. 
/RELATIVE 
The /RELATIVE qualifier informs RMSCNV that the output file 
is of relative organization. Regardless of their 


organization, all input files are read sequentially. 


The /RELATIVE qualifier is the equivalent of the /FO:REL 
qualifier in an RMSCNV command line. 


RMSCNV reads records from the input file and writes them 
into successive record cells of the output file, beginning 


with cell 1. If RMSCNV encounters a cell containing a 
record, it terminates with an error message. All records 
written to that point are in the output file. You should 
examine the two files to determine how far the processing 
went. 
/{NO]REPLACE 

The /REPLACE qualifier directs RMSCNV to supersede an 
existing sequential file. RMSCNV replaces a file in the 
output account with the same filename, type, and _ version 
number. You cannot use /REPLACE and /APPEND in the same 


command line. 


The /REPLACE qualifier is the equivalent of /SU in an RMSCNV 
command line. 


The default is /NOREPLACE, but the default action depends on 
whether the command line includes an /APPEND or not. If you 
specify /APPEND, RMSCNV performs the append operation. If 
you do not specify /APPEND, RMSCNV creates the next higher 
version of the file. 


/ SEQUENTIAL 


The /SEQUENTIAL qualifier informs RMSCNV that the output 
file is of sequential organization. Regardless of their 
organization, all input files are read sequentially. The 
default output file organization for RMSCNV is sequential. 


This qualifier is the equivalent of the /FO:SEQ qualifier in 
an RMSCNV command line. 


If you do not specify either the /APPEND or /REPLACE 
qualifier, and the output file is sequential, the output 
file need not exist before you issue the CONVERT command. 
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If the output file does not exist, RMSCNV creates an output 
file with the record attributes of the input file. RMSCNV 
then reads records from the input file and writes them 
sequentially into the new output file. 


If the output file already exists, and the command does not 
include the /APPEND qualifier, RMSCNV creates the next 
higher version of the file. RMSCNV then reads records’ from 
the input file and writes them sequentially into the new 
version of the output file. 


If the output file exists and you specify the /REPLACE 
qualifier, RMSCNV reads records from the input file and 
writes them sequentially into the output file, starting with 
the beginning of the file. 


If the output file exists and you specify the /APPEND 
qualifier, RMSCNV reads records from the input file and 
writes them into the output file, starting with the record 
position following the last record already in the file. 


/{NO]TRUNCATE 


Directs RMSCNV to truncate records read from the input file 
to the output file’s record length before writing them into 
the output file. The trailing bytes of the record are 
truncated. 


The default is /NOTRUNCATE. If you do not specify /TRUNCATE 
and the input records are too long, RMSCNV terminates. 


COPY 
3.13 COPY 


This command creates a sequential file copy of one or more 
sequential files, or of records with either indexed or relative 
file organization. 


Syntax 

COPY([/qualifier[s]] input_filespec[,s] output_filespec 
qualifier 

Can be one or more of the following: 


/{NO]CONTIGUOUS 
/REPLACE 

/DATE: dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 

/EXCLUDE: filespec 

/{NO]WARNINGS 

/[NO]PRESERVE_DATE 

/ALLOCATION: n[. ] 

/NONEW_VERSION 

/OVERLAY 

/ SHARED 

/ OWN 


With PRO/DECnet DCL extensions, the following qualifiers are 
also available: 


/CONCATENATE 
/DATA_TYPE 
/LOG 

/MACY11 | 
/NEW_VERSION 
/NOSPAN 

/PRINT 

/SUBMIT 
/TRANSFER_MODE 
/OWNER 
/PROTECTION 


COPY 


input_filespec 
Specifies the input file or files to be copied. 
You must have READ access to a file to copy it. 


Multiple filespecs, separated by commas, are accepted. 1 3 
you specify multiple input files, they will be concatenated 
in a single output file in the order that you specify them. 


output_filespec 


Specifies a single output file to which the input file or 
files is copied. 


You can change the name, type, and version number of the 
file when you enter this parameter. Wildcards in the place 
of the name and the type leave the name and type unchanged. 
If you use a wildcard in either of these fields, you must 
use a wildcard in both. 


COPY always creates the output file. For example, if you 
type: 


COPY FILE1.LIS FILE2.LIS 


and FILE2 already exists, COPY will create a new version of 
the file one higher than the existing version. If FILE2 
does not already exist, COPY will create a file with the 
name FILE2 and extension .LIS. If you specify a version 
number for the output file field, then a file of that 
version number is created. If such a file already exists, 
the operation fails. 


Wildcards are acceptable for output files if the destination 
is another directory. If you have multiple input files and 
use wildcards for the output file, you create multiple 
output files, each with the name and type of the 
corresponding input file. 


You can send copies to devices as well as to directories. 


You can also use the COPY command to create multiple copies 
of the same file with the same or different names. 


Prompts 


From? input_filespec[,s] 
To? output_filespec 


CORY 


Qualifiers 

/{NO]CONTIGUOUS 
Specifies that the output file must be contiguous. If this 
qualifier is not used, then only files that are already 
contiguous remain contiguous when copied. 
The default is /NOCONTIGUOUS. 

/REPLACE 
If the output file has the same name, type, and version 
number as an already existing file at the destination, the 


first file is deleted and the file you have sent replaces 
it. The name, type and version number stay as they were. 


/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the COPY command 
to affect only files created by the value specified for 
/DATE. 


/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the COPY 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the COPY 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the COPY command to affect only files 
created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the COPY 
command to affect only files created on the same day as the 
command is issued. 
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/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you don’t want COPY to 
affect certain files. The filespec argument to /EXCLUDE can 
contain wildcards, but the filespec must contain a version 
number, either explicitly or as the "*" wildcard. 


/{NO]WARNINGS 


The /[NO]WARNINGS qualifier specifies that the "No such 
file" error messages should not be displayed when the input 
files specified do not exist. 


/ALLOCATION:n[. ] 


The /ALLOCATION:n[.] qualifier specifies that n blocks of 
contiguous space be allocated for the new copy of the file. 
Unless you append the optional decimal point, the value n is 
interpreted as an octal value. | 


/NONEW_VERSION 


The /NONEW_VERSION qualifier prevents the version number 
from being automatically incremented when a file is copied. 
You must specify this qualifier when you copy all versions 
of a particular filename and type. 


/OVERLAY 


The /OVERLAY qualifier causes the contents of the input file 
or files to be copied into the output file. Whatever is 
currently in the output file is destroyed, although the file 
ID remains unchanged. The output file must exist before you 
issue the command. 


/([NO]PRESERVE_DATE 


The /PRESERVE_DATE qualifier specifies that the output file 
have the same creation date as the input file. This is the 
default. The /{[NO]PRESERVE_DATE qualifier specifies that 
the output file have the current date and time as the 
creation date. 


/ SHARED 


The /SHARED qualifier specifies that you want other users to 
be able to access the file while you are copying it. 
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/ OWN 


The /OWN qualifier changes the ownership of the file being 
copied to that of the destination directory. After 
execution, both directories own their respective copies of 
the file. If you do not specify /OWN, the original UIC owns 
both copies of the file. 


Additional Qualifiers Available with PRO/DECnet 

Command Qualifiers | 

/CONCATENATE 
The /CONCATENATE qualifier specifies that the output file 
should be a single file that contains all of the input files 


in the order specified. If wildcards are used in the input 
file specification, the files will be concatenated in random 


order. 

/ LOG 
The /LOG qualifier specifies that the names of files copied 
and their sizes in blocks are to be displayed as the 
operation is performed. 

/PRINT 
The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
file will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 

/SUBMIT 


The /SUBMIT qualifier specifies that the output file is a 
temporary file and will be submitted to the remote batch 
processor facility when copied. The file will be deleted 
after it is processed at the remote node. 


File Qualifiers 
/DATA_TYPE 


The /DATA_TYPE qualifier specifies how the data in the file 


is interpreted. With the COPY command, the DATA_TYPE 
qualifier takes either the ASCII or IMAGE argument. The 
default is IMAGE. /DATA_TYPE must appear after the file 


specification in the command line. 
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The ASCII argument transfers files in ASCII record mode and 

translates the records into an appropriate format for the 
remote system. You only need to use this argument when 
transferring text files to remote systems with file systems 
other than RMS. File transfers to VAX/VMS and PDP-11/RSX 
systems, which use RMS, are more efficiently performed using 
the default, IMAGE. 


The IMAGE argument transfers files with their current format 
and attributes. If a remote system cannot interpret that 
format, an error message will be displayed. If the file is 
an ASCII text file, you can recover by retrying with the 
ASCII argument. 


/MACY11 


The /MACY11 qualifier specifies that the input or _ output 
File on the remote TOPS-10 or TOPS-20 system is in MACY11 
format. This informs the remote DECsystem to handle the 
file appropriately when copying to or from the P/OS system. 
/MACY11 must appear after the file specification in _ the 
command line. 


/NEW_VERSION 


The /NEW_VERSION qualifier specifies that the output files 
be created with a version number higher than any existing 
files of the same name in the directory. /NEW_VERSION must 
appear after the file specification in the command line. 


/NOSPAN 


The /NOSPAN qualifier specifies that the output file be 
created with records that do not span block boundaries. 
Normally, only files that already have records that do not 
span block boundaries remain as such when copied. /NOSPAN 
must appear after the file specification in the command 
line. 


/TRANSFER_MODE 


The /TRANSFER_MODE qualifier specifies the method of 
packaging file data during a file transfer. For the COPY 
command, the TRANSFER_MODE qualifer takes the argument 
AUTOMATIC, BLOCK, or RECORD. AUTOMATIC is the default. 
/TRANSFER_MODE must appear after the file specification in 
the command line. 
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The AUTOMATIC argument causes DCL to select either BLOCK or 
RECORD after checking the file capabilities at the remote 
node. If you have problems transferring files with the 
AUTOMATIC argument, try specifying either BLOCK or RECORD. 
The BLOCK argument transfers files in block mode, using 
blocks of 512-byte sizes. This is more efficient than using 
record mode, but should only be used with systems that 
support RMS-1i1, such as VAX/VMS, PDP-11/RSX, or 
PDP-11/RSTS/E RMS FAL. 


The RECORD argument transfers a file one record at a time. 
A record is a logical unit of data ina file. 


/OWNER: [UIC] 


The /OWNER qualifier specifies the UIC of the output file. 
A UIC establishes the owner of a file. See the Tool Kit 
User’s Guide for a description of UIC. 


/PROTECTION: code 


This qualifier specifies the protection code applied to the 
output file. See the description of the SET PROTECTION 
command for details on the code. 


3.14 CREATE 


CREATE creates a sequential file and enables 


directly into the 


editor. 
Syntax 
CREATE filespec 


filespec 


file 


CREATE 


from your 


you to 
terminal 


type text 
without using an 


Specifies the name of the file to be created. 


As soon as the command is entered, 


line. The 
into the file. 


file is open for input. 
When you have finished entering 


CTRL/Z to close the file. 


If you want to create an empty sequential file, 


CTRL/Z first. 


If you use CTRL/U when creating a sequential file, 
eliminated, 
CTRL/U leaves a 


on the line 
other words, 
deletes a line. 


only editing 


Prompts 


File? filespec 
With PRO/DECnet DCL 
available: 


/CONTIGUOUS 
/LOG 

/MACY11 
/NEW_VERSION 
/NOSPAN 

/ {NO ]WARNINGS 
/PRINT 

/ REPLACE 

/ PROTECTION 
/OWNER 
/SUBMIT 


1s 


extensions, 


the 


down a 
Any text you type goes 
text, type 


the cursor moves 


Simply enter 


the text 


but not the line itself. In 
blank 
CTRL/U, CTRL/R, 
facilities 
sequential files at the terminal. 


line behind when it 


and the DELETE key are the 
available to 


you when creating 


following qualifiers are 


CREATE 


With PRO/DECnet, the CREATE command creates a file from _ records 
you type. In other words, when you press <DO> after entering the 
CREATE command, all subsequent keystrokes are entered into a file 
that you named with the CREATE command. To close and store the 
file, press <CTRL/Z>. 


Command Qualifiers 


/LOG 
The /LOG qualifier specifies that the names of files created 
and their sizes in blocks are to be displayed as the 
Operation is performed. 

/NOWARNINGS 
The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
Specified do not exist. 

/PRINT 
The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
file will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 

/ SUBMIT 


The /SUBMIT qualifier specifies that the output file is a 
temporary file. and will be submitted to the remote batch 
processor facility when copied. The file will be deleted 
after it 1S processed at the remote node. 


File Qualifiers 
/CONTIGUOUS 


The CONTIGUOUS qualifier specifies that the output file must 
be contiguous. /CONTIGUOUS must appear after the file 
Specification in the command line. 


/MACY11 


The /MACY11 qualifier specifies that the input or output 
file on the remote TOPS-10 or TOPS-20 system is in MACY11 
format. This informs the remote DECsystem to handle the 
file appropriately when copying to or from the P/OS system. 


CREATE 


/MACY11 must appear after the file specification in the 
command line. 


/NEW_VERSION 


The /NEW_VERSION qualifier specifies that the output files 
will be created with a version number higher than any 
existing files of the same name in the directory. 
/NEW_VERSION must appear after the file specification in the 
command line. 


/NOSPAN 


The /NOSPAN qualifier specifies that the output file will be 
created with records that do not span block boundaries. 
Normally, only files that already have records that do not 
span block boundaries remain as such when copied. /NOSPAN 
must appear after the file specification in the command 
line. : 


/REPLACE 


With the /REPLACE qualifier, if the output file has the same 
name, type, and version number as an already existing file 
at the destination, the first file is deleted and the file 
you have sent replaces it. The name, type, and version 
number stay as they were. /REPLACE must appear after the 
file specification in the command line. 


/OWNER: [UIC] 


This qualifier specifies the UIC of the file. A UIC 
establishes the owner of a file. See the Tool Kit User’s 
Guide for a description of UIC. 


/PROTECTION: code 
This qualifier specifies the protection code applied to the 


output file. See the description of the SET PROTECTION 
command for details on the code. 


CREATE /DIRECTORY 


3.15 CREATE/DIRECTORY 


CREATE/DIRECTORY creates a User File Directory (UFD) on a 
FILES-11 volume and enters the UFD into the volume’s Master File 
Directory (MFD). 


Syntax 


CREATE/DIRECTORY [device: ] [dirspec] [qualifier[s]] 


device: 


Specifies the name of the device on which you want the 
directory created. The default is SyY0:. If you do not 
specify a device or volume name, a directory is created on 
the default volume, SYO:. 


dirspec 


Specifies the name of the directory that you want to create. 
You must specify the dirspec parameter, and you must enclose 
it in square brackets. 


qualifier 


One or more of the following: 


/NOWARNINGS 
/OWNER_UIC: [UIC] 
/PROTECTION: (code) 


Prompts 


Directory? [device: ][dirspec] 


Qualifiers 


/NOWARNINGS 


Supresses error messages resulting from the command. 


CREATE/DIRECTORY 


/OWNER_UIC: [UIC] 


Specifies the User Identification Code (UIC) of the 
directory’s owner. A UIC establishes the protection status 
of the directory. See the Tool Kit User’s Guide for details 
on UICs and file protection. 


The default ownership of a directory depends on the device 
on which it is created. If the directory is created on LBOQ: 
or LB1: on a stand-alone or server system, the UIC is 
[377,0]. If the directory is created on LBO: or LBil: ona 
workstation, the UIC is [377,x], where x is the number 
assigned when the workstation was defined. For any other 
device specification, the directory is owned by the issuer 
of this command. You can specify any UIC as the owner by 
using this qualifier. However, a nonprivileged user cannot 
always create files in a directory that is owned by a 
different UIC. 


CREATE/DIRECTORY 


/PROTECTION: (CODE) 


Defines the kinds of access to the directory for different 
categories of users. 


The code takes the following format: 


((SYSTEM(:n)]],(OWNER[:n]],[GROUP[:n]],[WORLD[:n]]) 


where: 

SYSTEM is the system level protection code 
OWNER is the owner level protection code 
GROUP is the group level protection code 
WORLD is the world level protection code 
n 


The type of access that is to be allowed. The value 
for n can be any or all of the following values, in any 
order: 


R-Read allowed. Read access allows qualified users’ to 
read, copy, print or type (scroll) the files ina 
directory. 


W-Write allowed. Write access allows qualified users 
or their applications to create files in the directory. 


E-Extend allowed. Extend access allows qualified users 
or their tasks to change the amount of disk space 
allocated to the directory file. 


D-Delete allowed. Delete access allows qualified users 
(or their applications) to delete files listed in the 
directory. 


Only the categories that you specify gain access to your 
files; all other categories of users are denied access. The 
default protection for directories is [RWE,RWE,R,R]. 


Note that the SET PROTECTION/DEFAULT command establishes the 
default protection for all files, not directories, created 
during the current login session. | 
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DEASSIGN 


This command deletes a logical name assignment created through 
the use of the ASSIGN command or DEFINE command. 


Syntax 


DEASSIGN[/qualifier[s]] [logical_name] 


qualifier 


Can be any combination of the following: 


/USER 
/SESSION 
/OYSTEM 
/ALL 


logical_name 


Is the name of a unique logical name. If you created the 
logical name uSing quote characters, you must use quote 
characters in the logical name to perform the DEASSIGN. 


Prompt 


Logical name? logical_name 


Qualifiers 


By default, if you do not specify one of the qualifiers /USER, 
/SESSION, or /SYSTEM, P/OS performs the operation in the session 
logical name table. 


/ALL 


Indicates that all logical names in the specified logical 
name table be deassigned. DIGITAL does not recommend that 
you delete all logical names in the SYSTEM logical name 
table. 


/SESSION 


Limits the search for the logical to the session logical 
name table. This is the default. 3 


DEASSIGN 


/ SYSTEM 


Limits the search for the logical to the system logical name 
table. You should not delete any P/OS standard logical 
names defined in this table. See the Tool Kit User’s Guide 
for a list of these logical names. 


/USER 


Limits the search for the logical to the user logical name 
table. 


DEBUG 


3.17 DEBUG 


This command executes a debugger that you have built into your 
task. The command sets the T-bit in the task’s Processor Status 
Word (PSW). To build a debugger into your task, you must specify 
the /DA qualifier on the PAB command line you use to build your 
task or use the /DEBUG qualifier with the LINK command. 
Syntax 

DEBUG taskname 


taskname 


Is the name of the task that you want to debug. 
Prompt 


None 


DEFINE 


3.18 DEFINE 


This command creates a logical name and assigns an equivalence 
string to the specified logical name. An equivalence name can be 
a device name, another logical name, or a file specification. 


To specify the logical name table where you want to enter a 


logical name, use /USER, /SESSION, or /SYSTEM. If you do not 
explicitly specify a logical name table, the default is /SESSION. 


Syntax 

DEFINE[/qualifiers] logical_name equiv_name 
qualifiers 
Can be one or more of the following: 


/USER 
/ SESSION 

/ SYSTEM 

/ FINAL 
/TRANSLATION_ATTRIBUTES: [ (keyword[,...])] 


logical_name 


Specifies the logical name string. The logical name string 


can contain from 1 to 255 characters. If the logical name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") in the places 


where you want a quotation mark to appear. 


Note that if you enclose a logical name string in quotation 
marks the case of alphabetic characters is preserved. 


equiv_name 


Defines the equivalence name to be associated with the 
logical name in the specified logical name table. The 
equivalence name string can contain from 1 to 255 
Characters. If the equivalence name contains quotation 
marks, enclose the string in quotation marks and use _ two 
sets of quotation marks ("") in the places where you want a 
quotation mark to appear. 


Note that if you enclose an equivalence name string in 
quotation marks, the case of alphabetic characters is 
preserved. 


SHOW TERMINAL 


Prompts 


None 
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3.87 SHOW USERS 


When the SHOW USERS application is installed on your system and 
the target systems, the SHOW USERS command displays the terminal 
name, current user identification code (UIC), date and time of 
login, number of currently active tasks, and usernames of all 
users who are logged on the system. 
Syntax 
SHOW USERS[/qualifier] 
qualifier 
/NODE 
Prompt 
None 
Qualifiers 
/NODE=[(node name[,...])] 
The /NODE qualifier displays users who are logged on _ the 
local system only. The optional parameter list allows you 
to display users who are logged on the node or nodes you 


specify. The default is to display all users who are logged 
on to all workstations in your server environment. 
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3.88 SPAWN 


The SPAWN command allows tasks to be executed in the background. 
These tasks allow you to continue to use the terminal. For 
example, SPAWN can initiate a task building session, allowing you 
to perform other tasks. 
SPAWN should not be used with tasks that attach the terminal. 
SPAWN will return an error message, if it was asked to initiate 
an uninstalled task. 
Syntax 

SPAWN cmd 
cmd 

Is any PRO/Tool Kit Command Language command. 


Prompts 


None 
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3.89 START 


START resumes the execution of a task that was halted by a STOPSS 
directive. Starting a task that has been stopped is different 
from continuing a suspended task. Nonprivileged users can resume 
tasks initiated from their own terminals. Privileged users can 
resume any stopped task. 


Syntax 


START[/TERMINAL:ttnnn:] taskname 


qualifier 


/TERMINAL: ttnnn: 


taskname 


The name of the task you want to start. 


Prompt 


Taskname? 


Command Qualifiers 
/TERMINAL: ttnnn: 


Allows you to resume a task running on some other terminal. 
This is a privileged qualifier. 
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3.90 START/UNBLOCK 


This command continues the execution of a task that was’ blocked 
by the STOP/BLOCK command. Nonprivileged users can unblock any 
task running from their own terminals. Privileged users’ can 
unblock any task. 
Syntax 

START/UNBLOCK([/TERMINAL:ttnnn:] taskname 
qualifier 

/TERMINAL:ttnnn: 
taskname 

The name of the task to be unblocked. 


Prompt 


Taskname? 


Qualifier 
/TERMINAL: ttnnn: 


Specifies that a task running from the specified terminal is 
to be unblocked. This is a privileged qualifier. 
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STOP/BLOCK 


3.91 STOP/BLOCK 


This command blocks an installed, active task. After execution 
of this command, the task no longer executes or competes for 
memory (refer to START/UNBLOCK). Nonprivileged users can block 
tasks running from their own terminals. Privileged users can 


block any task. 
Syntax 
STOP/BLOCK[ /TERMINAL:ttnnn:] taskname 
qualifier 
/TERMINAL: ttnnn: 
taskname 
The name of the task to be blocked. 
Prompt 
Taskname? 
Qualifier 
/TERMINAL: ttnnn: 


Specifies that a task running from the specified terminal is 
to be blocked. This is a privileged qualifier. 


3-206 


SUBMIT/REMOTE 


3.92 SUBMIT/REMOTE 


With PRO/DECnet only, SUBMIT/REMOTE directs an existing command 
file ona remote node to be executed. The file is queued to the 
remote node’s command file or batch file processor. If the 
command file is not on the node where it will be executed, you 
may want to use a COPY command with a /SUBMIT qualifier. 

The success of the command does not guarantee that the batch or 
command file was executed successfully, only that the execution 
request was given successfully to the remote processor. 

Syntax 


SUBMIT/REMOTE[ /qualifier[{,s]] commandfile[,s] 


qualifier 
Can be one or more of the following: 


/ LOG 
/NOWARNINGS 


commandfile 
The output file descriptor for each remote node command file 
that you want to execute. Command files are not deleted 
after execution. 


Prompts 


File(s)? commandfile[,s] 


Qualifiers 
JOG 


Specifies that the names of files submitted are to be 
displayed as the operation is performed. 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the input files specified do not exist. 
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3.93 TYPE 


This command displays the contents of a file or group of files on 
the terminal. 


Syntax 
TYPE[/qualifier[s]] filespec[,s] 
qualifier 
Can be one or more of the following: 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/ THROUGH: dd-mmm-yy 
/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 
/EXCLUDE: filespec 
/NOWARNINGS 
/ SHARED 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/ LOG 
/MACY11 
filespec 
Is the name of the file to be displayed. 
Prompts 
File(s)? filespec[,s] 
Qualifiers 
/DATE:dd-mmm-yy 
The /DATE qualifier specifies that you want the TYPE command 


to affect only files created by the value specified for 
/DATE. 
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/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the TYPE 
command to affect only files created on or since the value 
specified by /SINCE. 

/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the TYPE 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the TYPE command to affect only files 
created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the TYPE 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the TYPE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the input files specified do not exist. 


/ SHARED 
Specifies that other users are able to access the file while 
you are typing it. 

Additional Qualifiers Available with PRO/DECnet 

Command Qualifiers 


/ LOG 


Specifies that the names of files typed and their sizes are 
to be displayed as the operation is performed. 
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File Qualifiers 
/MACY11 


Specifies that the input or output file on the - remote 
TOPS-10 or TOPS-20 system is in MACY11 format. This 
qualifier is used to inform the remote DECsystem to handle 
the file appropriately when copying to or from the P/OS 
system. /MACY11 must be entered after the file 
specification in the command line. 
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3.94 UNLOAD 


The UNLOAD command removes a loadable device driver from memory. 
Note that the device driver data base will not be removed from 
the system. Reboot the system to remove the driver data 
structures. 


Note the following restrictions: 


e If a device is mounted, attached, or has outstanding I/O, its 
driver cannot be unloaded. 


e The UNLOAD command cannot remove a data base from memory, 


even if the data base was loaded by means of the LOAD 
command. 


Syntax 
UNLOAD dd: 


dd: 
Is a two-character ASCII device name. 


Prompt 


Device? dd: 
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3.95 UNLOCK 


UNLOCK unlocks locked files. Locked files are files that have 
been improperly closed because a task aborted or _ stopped 
execution while the file was open. Locked files are identified 
by an L in the directory listing. 
Syntax 
UNLOCK([ /qualifier[s]] filespec[,s] 
qualifier 
Can be one or more of the following: 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH :dd-mmm-yy 
/ TODAY 
/EXCLUDE: filespec 
/{NO]WARNINGS 
filespec 
Is the name of the file to be unlocked. 
Prompts 
File(s)? Filespec([,s] 
Qualifiers 
/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the UNLOCK 
command to affect only files created by the value specified 
for /DATE. 


/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the UNLOCK 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-yy 
The /THROUGH qualifier specifies that you want the UNLOCK 


command to affect only files created on or before the value 
specified by /THROUGH. 
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/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the UNLOCK command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the UNLOCK 
command to affect only files created on the same day as the 
command 1s issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the UNLOCK 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "x" 
wildcard. 


/{NO]WARNINGS 
The /[NO]WARNINGS qualifier specifies that the "No- such 


file" error messages should not be displayed when the input 
files specified do not exist. 
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CHAPTER 4 
THE INDIRECT COMMAND PROCESSOR 


This chapter describes the Indirect Command Processor 


("Indirect") and indirect command files. Section 4.33 through 
4.54 describe the processor directives that control execution of 
Indirect. The final two sections in the chapter’ provide 


information on compatibility with RSX systems, as well as errors 
that Indirect can return. 


4.1 INDIRECT COMMAND FILES >. 


An indirect DCL command file is a text file containing a list of 
DCL-specific command lines and special directives that allow you 
to control command file processing. The indirect command 
processor reads the indirect DCL command file, interprets the 
directives, and passes the DCL commands to DCL. 


To initiate an indirect DCL command file, enter the file 
specification, preceded by an at sign (@), whenever DCL can 
accept input. For example: 


S$ @DCLIPT.CMD 
The default file type for indirect DCL command files is _ .CMD. 
Thus, the command line in the previous example could also be 
input as follows: 


S$ @DCLIPT 


Indirect DCL command files can also be nested. The maximum level 
of nesting is four. 


Note that the Indirect directives described in this chapter can 
only be used in indirect DCL command files. 


INDIRECT COMMAND PROCESSOR 


4.2 INDIRECT COMMAND PROCESSOR 

When processing an indirect command file, the Indirect task first 
reads the command file and interprets each command line either as 
a command to be passed directly to DCL or as a request for action 
by Indirect. The directives to Indirect are distinguished by a 
period (.) as the first character in the line. 


The Indirect directives form a procedural language that allows 
you to: 


@e Define and assign values to logical, numeric, and string 
symbols 


® Substitute a symbol’s value into any line of the command file 
e Perform arithmetic functions 

@ Manipulate strings 

@e Display text on the user’s terminal screen 

@® Ask questions of a user 

@e Control the flow of a sonmane file 

e Call subroutines 

@e Detect error conditions 

e Test symbols and conditions 

@e Create and access data files 

@e Parse commands and data 

@ Enable or disable any of several operating modes 


e Display forms and control user entry of data 


Two directives (.BEGIN and .END) permit you to use. block 
structure in the command file. Modular, block-structured command 
files are easier to debug and maintain. More importantly, 


Begin-End blocks isolate local symbol definitions as well as 
labels, and thus conserve symbol table space. 


When you define a symbol, Indirect creates an entry for the 
definition in an internal symbol table. These symbol table 
entries retain their definitions throughout execution of the 
command file if defined locally, or throughout the execution of 
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all levels of nested command files if defined globally. Local 
symbols defined within a block, however, retain their definitions 
only throughout the execution of the commands within that block; 
they are erased from the symbol table when Indirect encounters an 
.-END directive. 


An Indirect directive (.ENABLE GLOBAL) allows the definition of 
some symbols as global to all file levels. Otherwise, each time 
Indirect enters a deeper level, it masks all symbols defined by 
the previous level out of the symbol table so that only symbols 
defined in the current level are available. These symbols are 
local only to the level of the file in which they are defined. 
When control returns to a previous level, the symbols defined in 
that level become available once again and the ones from the 
deeper level are lost. 


When Indirect reaches the end of the highest level indirect 
command file, it displays the following message (unless inhibited 
by the .DISABLE DISPLAY directive): 


S$ @<EOF> 
and then exits. DCL then prompts for a command from the 
keyboard. Indirect displays on the requesting terminal’s screen 


every DCL command line as it is executed. 


An Indirect file can also include comments, which the processor 
prints at the terminal screen. Comments that begin a line 
interpreted by DCL have a leading semicolon (;). Comments that 
appear after the start of a DCL command line have a leading 
exclamation point (!). All lines in an indirect command file 
that begin with a period in column 1 followed by a semicolon (.;) 
are treated as comments but are not displayed when the file is 
processed. 


Indirect attaches the terminal while processing contiguous 
comment lines that begin with a semicolon. This permits you to 
type CTRL/O and suppress a lengthy comment. Output is resumed by 
typing another CTRL/O or is resumed at the next DCL command line 
or Indirect directive statement in the command file. 
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If the specified command file cannot be found in the current 
directory, Indirect will attempt to translate the logical name 
INDSCOMMAND_LIBRARY and look for the command file there. This 
permits a user to place commonly used command files in one place. 
The following DCL command establishes this behavior. 

S ASSIGN DW1i:[USERLIBRY] INDSCOMMAND_LIBRARY 
Subsequently, the user command: 


S @COMPILE 


results in Indirect first looking for COMPILE.CMD in the current 
default directory and, if not found, looking for: 


DW1: [{USERLIBRY]COMPILE.CMD 
Note that the PRO/Tool Kit uses LB:[1,2] as the initial value of 


INDSCOMMAND_LIBRARY. You can specify your own initial value in 
the file START.CMD. 


4.3 SUMMARY OF INDIRECT DIRECTIVES 


The Indirect directives described in this chapter are listed here 
by category. 


Label Definition 


.label: Assigns a name to a line in the command 
file so that the line may be referenced. 


Symbol Definition 


-ASK Defines or redefines a logical symbol and 
assigns the symbol a true or false value. 


. ASKN Defines or redefines a numeric symbol and 
assigns the symbol a numeric value. 


-ASKS Defines or redefines a string symbol and 
assigns the symbol a character. string 
value. 


. ERASE 


~SETT/.SET 


-SETN 


-SETD/.SETO 


-SETL 


-SETS 


. TRANSLATE 


File Access 


.DATA 


. CHAIN 


-CLOSE 


- OPEN 


-OPENA 


-OPENR 


. PARSE 
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Deletes all local Or global symbol 
definitions or a single global symbol 
definition. | 


Defines or redefines a logical symbol and 
assigns the symbol a true or false value. 


Defines or redefines a numeric symbol and 
assigns the symbol a numeric value. 


Redefines the radix of a numeric symbol. 


Defines or redefines a logical symbol and 
assigns the symbol a true or false value. 


Defines or redefines a string symbol and 
assigns the symbol a character’ string 
value. 


Attempts to translate a logical name and 
return its equivalence value. 


Specifies a single line of data to output 
to a file. 


Closes the current indirect file and uses 
commands from another file. 


Closes a file. 

Creates and opens an output data file (if 
the file exists, creates a new version and 
opens it). 

Opens an existing file and appends 
subsequent data (does not create a new 
version). Defaults to .OPEN if the file 


does not exist. 


Opens a file for reading with the .READ 
directive. 


Parses strings into substrings. 
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- READ 


Logical Control 
- BEGIN 
. END 


EXIT 


- GOSUB 


- GOTO 


- ONERR 


- RETURN 


eo LOP 


Logical Tests 


rae 


.IFACT/.IFNACT 


slFDF/ ~LFNDE 
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Reads a record from ae file into a 
Specified string variable. 


Marks the beginning of a Begin-End block. 
Marks the end of a Begin-End block. 


Terminates processing of either Indirect 


or the current command file, returns 
control to the invoking terminal or to the 
previous level, and optionally sets 


Special symbol <EXSTAT> value. 


Calls a subroutine within the command 
file. 


Branches to a label within the command 
file. 


Defines logical end-of-file. Terminates 
file processing and exits. This directive 
is equivalent to the .STOP directive. 


Branches to a label upon detecting a 
Specific Indirect error condition. 


Effects an exit from a subroutine and 
returns to the line immediately following 
the subroutine call. 


Terminates indirect command file 
processing and optionally sets Indirect 
exit status. This directive is equivalent 
to the logical end-of-file (/) directive. 


Determines whether or not a symbol 
satisfies a condition. 


Determines whether or not ae task is 
active. 


Determines whether or not a symbol is 
defined. 


. IFENABLED/ 


- TFDISABLED 


~IFINS/.IFNINS 


- IT FLOA/.IFNLOA 


.IFT/.IFF 


- TEST 


. TESTDEVICE 


-TESTFILE 


. TESTPARTITION 


-TESTSYSTEM 
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Tests the .ENABLE/.DISABLE options. 


Determines whether or not ae task is 
installed in the system. 


Determines whether or not a device driver 
is loaded. 


Determines whether a logical symbol is 
true or false. 


Tests the length of a string symbol or 
locates a substring. 


Returns information about a device in the 
system. 


Determines if a specified file exists and 
determines the physical device associated 
with a logical device name (performs 
device translation). 


Returns information about a partition in 
the system. 


Returns information about the presence of 
certain operating system features. 


Enable or Disable an Operating Mode 


. ENABLE/.DISABLE 


Enables or disables Control of the 
following modes: 


substitution 

timeout parameter 
lowercase 

terminal attachment 
data 

global symbol 

symbol radix 

command line echo 
command display 

field display 

command passing to DCL 
file deletion 

truncate error suppression 
escape 

CTRL/Z exit 

overflow 
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Increment or Decrement Numeric Symbols 


~ INC Adds one to a numeric symbol’s value. 
.DEC Subtracts one from a numeric symbol’s 
value. 


Execution Control 


. DELAY Delays the execution of an indirect 
command file for a specified period of 
time. 

. PAUSE Is a no-op under the PRO/Tool Kit. Te 
does not suspend execution of Indirect. 

.WAIT Is a no-op under the PRO/Tool Kit. It has 
no effect. 

.XQT Is a no-op under the PRO/Tool Kit. It 
passes the DCL command line to DCL. 
Indirect does not proceed until that 


command is complete. 


Special Purpose 


. FORM Provides access to the PRO/FMS form 
driver, allowing FMS commands to be passed 
to FMS. 


4.4 SYMBOLS 


The Indirect Command Processor enables you to define symbols. 
These symbols can then be tested or compared to control flow 
through the indirect command file. They may also be substituted 
in DCL commands, data records for data files, or comments to be 
displayed on the screen. 


Symbol names are ASCII strings from one through six characters in 
length. They must start with a letter (A through Z) or a dollar 


sign ($). The remaining characters must be alphanumeric or a 
dollar sign. 


There are three symbol types: 


@ Logical 


SYMBOLS 


® Numeric 

e String 
A logical symbol has either a true or false value. 
A numeric symbol can have a numeric value in the range of 0 
through 65535 (decimal). The symbol can be defined to have 
either a decimal or octal radix. The radix is relevant only when 


the symbol is substituted. 


A string symbol has as its value a string of ASCII characters, 
with a length of 0 through 132 (decimal) characters. 


A symbol’s type (logical, numeric, or string) is defined by the 
first assignment directive that assigns a value to the symbol. 
Assignment directives can assign: 


@e A true or false value to define a logical symbol (defined by 
»ASK, «SETL; ~SErT, oT .«SETF):. 


@ An octal or decimal number to define a numeric. symbol 
(defined by .ASKN, .SETN, .SETO, or .SETD). 


@e A character string to define a string symbol (defined by 
-ASKS, .READ, or .SETS). 


4.4.1 Special Symbols 


Indirect automatically defines special symbols dependent upon 
specific system characteristics and the replies to queries 


presented during command file execution. As with symbols, 
special symbols can be compared, tested, or substituted and 
consist of three types: logical, numeric, and string. All 


special symbols have a common format--angle brackets (<>) enclose 
the special symbol name. 


4.4.1.1 Special Logical Symbols - The special logical symbols 
are assigned a true or false value under the following 
circumstances: 
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Symbol 


<ALPHAN> 


<DEFAUL> 


<EOF> 


<ERSEEND>D 


<ESCAPE> 


<FALSE> 


<NUMBER> 


SYMBOLS 


Value 


Set to true if last string entered in response 
to an .ASKS directive or tested with a .TEST 
directive contains only alphanumeric characters. 
An empty string also sets <ALPHAN> to true. 


set to true if answer to last query was 
defaulted (the <RETURN> key was pressed once) or 
a timeout occurred. 

Set to true if the last .READ or .ASKx directive 
resulted in reading past the end of the file. 
Otherwise, <EOF> is set to false. 


Set to true if any of the following conditions 
are true. 


@® <FILERR> is less than 0, if a negative error 
code was returned 


e If an exit status <EXSTAT> value worse than 
<WARNING> was returned 


@ <EOF> is set to true 
e If you used the command line .SETT <ERSEEN> 


The command line .SETF <ERSEEN> sets the 
following conditions: 


@® <FILERR> is set to 0 

@e <EXSTAT> is set to 0 

e <EOF> is set to false 

Set to true if last question was answered with 
an ALTmode or ESCape. Otherwise, <ESCAPE> 1s 


set to false. 


Logical constant used for comparisons with the 
.IF directive or as a default for the .ASK 
directive. 


Set to true if the last string entered in 
response to an .ASKS directive or tested with a 


.TEST directive contains only numeric 
Characters. An empty string also sets <NUMBER> 
CO Crue. 


SYMBOLS 


<OCTAL> Set to true if the answer to the last .ASKN 
directive or the radix of the numeric symbol 
tested in the last .TEST directive is octal or 
if the last string tested with a .TEST directive 
contained all numeric characters in the range 0 
through 7. 


<PRIVIL> Set to true if the current user is' privileged. 
Its value is derived from the flag contained in 
the terminal data base. The flag is set when 
IND executes. 


<RAD50> Set to true if last string entered in response 
to an .ASKS directive or tested with a .TEST 
directive contains only Radix-50 characters. 
Radix-50 characters are the uppercase 
alphanumeric characters plus period (.) and 
dollar sign (S$). A blank is not a Radix-50 
character in this context. An empty string also 
sets <RAD50> true. 


<TIMOUT> Set to true if timeout mode is enabled and the 
last .ASKx directive timed out waiting for a 
user response. 


<TRUE> Logical constant used for comparisons with the 
.IF directive or as a default for the .ASK 
directive. 


4.4.1.2 Special Numeric Symbols - The special numeric’ symbols 
are assigned the following values: 


Symbol Value 


<ERRCTL> Controls the way in which Indirect processes 
errors. The symbol is treated as an 8-bit mask. 
For each class of error that a user’sS = .ONERR 
target routine processes, the appropriate bit is 
set in the mask. If the bit is clear, Indirect 
exits after printing the error information. See 
Section 4.34 for details on .ONERR. 


<ERRNUM> 


<ERRSEV> 


<EXSTAT> 


<FILERR> 


SYMBOLS 


If the eighth bit, the sign bit or 200 (octal), 
is set, Indirect does not print any information 
about the error. 


The initial default value for <ERRCTL> is 1, 
which implies that only class 1 errors can be 
handled with an .ONERR address, and that error 
messages will be printed. Note that if you 
attempt to trap errors other than default class 
1, processing cannot continue in most cases. 
The error service routine is limited to a_ fatal 
error message and .EXIT. The internal state of 
Indirect is indeterminate in all but class 1 
error cases. 


See Section 4.56.2 for a list of error messages 
and their asigned values. 


Assigned the class number of an error that 
Indirect has finished processing. This value 
can be used for processing specific error types 
with an .ONERR routine. 


Assigned the error severity mask associated with 
the error that Indirect has finished processing. 
This bit mask corresponds to the bit mask 
<ERRCTL> used to control the processing. 


Assigned a numeric value depending upon the 
status of the last DCL command executed. User 
programs can generate any 16-bit value as an 
exit status. Most DIGITAL-sSupplied programs, 
however, exit with one of the following status 
values: 


Value 


QO Warning 

1 Success 

2 Error 

4 Severe Error 


Assigned the FCS-11 or I/O driver status code 
resulting from a .TESTFILE, .OPENx, or .READ 
directive operation. See Appendix B for a 
description of the codes. 


<FILER2> 


<FORATT> 


<MEMSIZ> 


<SPACE> 


<STRLEN>D 


<SYMTYP> 


<SYSTEM> 


<SYUNIT> 


<TICLPP> 


<TICWID> 


<TISPED> 


SYMBOLS 


Assigned the second error code word that is 
returned by the FMS-related .FORM command. 


Assigned the octal value of the file attributes 
that were used to open the data files. 


Assigned the value of the current system memory 
size in K words (K is 1024.). 


Assigned the number, in octal, of free bytes in 
the internal symbol table for Indirect. The 
number does not reflect the amount of space that 
could be gained by the automatic extension of 
the Indirect task. 


Assigned the length of the string entered in 
response to the last .ASKS directive or the 
string tested by the last .TEST directive. 


Assigned the numeric code for the type of symbol 
tested with a .TEST directive. The symbol types 
have the following code numbers: 


String - 4 
Numeric - 2 
Logical - 0 


Assigned an octal number to represent the 
operating system on which Indirect is running. 
The value 11 is for the P/OS system. 


Assigned the unit number of the user’s default 
device (SY:). 


Assigned the current page length setting for the 
screen. 


Assigned the current page width setting for’ the 
screen. 


Assigned the baud rate for transmitting 
characters from the host system to the terminal. 
Indirect attemtps to determine the baud rate 
when you first invoke it. This information is 
useful for determining the quality and quantity 
of information to be transmitted. The following 
list gives the octal value that corresponds’ to 
each baud rate. 


<UUTYPE> 


4.4.1.3 


Special String Symbols - The special string symbols 


SYMBOLS 


Octal Value Baud Octal Value Baud 
1 or 0 0 13 1200 
2 50 14 3 1800 
3 75 15 2000 
4 100 16 2400 
5 110 17 3600 
6 134 20 4800 
7 150 21 F200 

10 200 22 9600 

sla 300 23 EXTA 

12 600 24 EXTB 


Assigned the terminal type of the terminal from 
which Indirect is running. The Professional 
terminal type is 35. 


assigned the following string values. 


Symbol 


<ACCOUN> 


Value 


(RSX-11M-PLUS and P/OS systems only.) Assigned 
certain accounting information from a user’s 
accounting block (UAB). The information is in 
the following format (note the trailing comma): 


unam,sessid,accnum,cpu,dir,qio,tas,atsks 
unam The first 14 characters of the user 


name as it appears in the system 
account file. 


sessid Session ID, null on P/OS. 

accnum Account number, null on P/OS. 

cpu CPU time used since login, null on 
P/OS. 

dir Number of system directives issued 


Since login, null on P/OS. 


qio Number of QIO directives issued since 
login, null on P/OS. 


tas Number of tasks run since login, null 
on P/OS. 
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are 


<CLI> 


<DATE> 


<DIRECT> 


<EXSTRI> 


<FILATR> 


<FILSPC> 


<LOGDEV> 


<LOGUIC> 


<NETNOD> 


SYMBOLS 


atsks Number of active tasks, null on P/OS 


Assigned the acronym (3 through 6 letters) of 
the current command line interpreter. This 
symbol is fixed at "DCL" under the PRO/Tool Kit. 


Assigned the current date. The date format is 
dd-mmm-yy. 


Assigned the name of the current default 
directory; the format is [ddddddddd]. 


Contains the string results from a more deeply 
nested indirect command file. The results are 
sent to the calling command file. Cleared after 
each DCL command. 


Assigned the seven words of file attribute 
information contained in the FCS-11 File 
Descriptor Block (FDB). 


Assigned the fully-qualified specification for 
the file referred to with the last  .OPEN, 
.OPENA, -~OPENR, or .TESTFILE directive 
operation, or in the last specification fora 
nested command file. 


Assigned the device name and unit number of the 
user’s login account on multiuser protection 
systems. On other systems, <LOGDEV> is assigned 
SYO: at the time IND is invoked. 


Assigned the login UIC of the current user _ on 
multiuser protection systems; the format is 
[ggg,mmm]. On other’ systems, <LOGUIC> is 
assigned the current default UIC. 


Assigned the DECnet node name of the system. If 
the asystem is not on the DECnet system, 
<NETNOD> is assigned the string PRO. 


SYMBOLS 


<SYSDEV> Assigned the physical name for the boot device 
for the system. The device name is in the form 
ddn. 

<SYDISK> Assigned the device mnemonic (two letters) of 


the user’s default device (SY:); format is dd. 


<SYSID> Assigned the operating system’s baselevel 
number. 

<TIME> Assigned the current time; format is hh:mm:ss. 

<UIC> Assigned to default UIC. 


4.4.2 Numeric Symbols and Expressions 


A numeric symbol is a string of digits representing a value in 
the range of 0 through 177777 (octal) (0 through 65535 decimal if 
immediately followed by a period or if decimal mode has_ been 
enabled). Tf an arithmetic operation yields a result outside of 
this range, a fatal error occurs and the following message is 
displayed: 


IND -- NUMERIC UNDER- OR OVERFLOW 


A numeric symbol or constant may be combined with another numeric 
symbol or constant by a logical or arithmetic operator to form a 
numeric expression. Arithmetic operators are used to add (+), 
subtract (-), multiply (*), and divide (/). Logical operators 
are the inclusive OR (!), logical AND (&), and NOT (#). No 
embedded blanks or tabs are permitted between operators. 


Numeric expressions are evaluated from left to right unless 
parentheses are used to form subexpressions that are evaluated 
first. For example, the directive lines: 


-SETN Ni 2 
~-SETN N2 3 
-SETN N3 N1+N2*4 


assign numeric symbol N3 the value 24 (octal), whereas’ the 
following directive lines assign numeric symbol N3 the value 16 
(octal): 


.SETN Ni 2 
.SETN N2 3 
.SETN N3 N1+(N2*4) 
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Numeric expressions are permitted as second operands in numeric 
-IF and .SETN directives. They are also permitted as range and 
default arguments in .ASKN and .ASKS directives. The directives 
-EXIT and .STOP permit numeric expressions to represent exit 
status. 


With each numeric symbol, Indirect associates a radix -- either 
octal or decimal. The radix of a numeric symbol changes each 
time the symbol is assigned a new value. If you use a numeric 
expression to assign a new value to a symbol and all operands in 
the expression are octal, then the symbol is set to octal. Tf 
any operand in the expression is decimal, the symbol is set to 
decimal. For example: 


-SETN N2 3. 

-SETN N3 N1+3 
.SETN N3 N1i+3. 
~SETN N3 N1+N2 


N2 1S decimal 
N3 is octal 

N3 is decimal 
N3 is decimal 


You can also assign a new value to a symbol with the  .ASKN 
directive. 


The .SETO and .SETD directives allow you to change the radix of a 
numeric symbol without changing the value of the symbol. For 
example: 


-SETN Ni 10. r oNd 
.SETO N1 { NI 


10 decimal 
12 octal 


The radix of a numeric symbol does not affect arithmetic 
operations or comparisons. The radix is important only when 
substituting a numeric symbol into a string. If the radix of the 
symbol is octal, the value of the symbol is substituted into the 


string as an octal number. If the radix is decimal, the value is 
substituted as a decimal number. For example: 

~OETN Ni 10. ! Ni = 10 decimal 

> Ni = ‘Ni’ ! Displayed as ; Ni = 10 

~SETO Nl ! Make N1 octal 

; N1 = ‘N11’ ! Displayed as ; Ni = 12 


If you substitute a numeric symbol into a string and _ the 
substituted number is decimal, a period (.) following the symbol 
name causes a trailing period to be included in the _ string 
(following the substituted number). For example: 


-SETN Ni 10. ! Ni = 10 decimal 

; N1 = ‘'N1.’ ! Displayed as ; Ni = 10. 
-SETO Ni ! Make Ni octal 

> N1 = 'N1.? ! Displayed as ; Ni = 12 


SYMBOLS 


You can also force a numeric symbol to be substituted as an octal 
or decimal number by using a substitution format control string. 
For example: 


-SETN Ni 10. ! Ni = 10 decimal 
; NL = 'N1%D’ ! Displayed as ; N1 = 10 
; NL = 'N1%0’ ! Displayed as ; N1 = 12 


4.4.3 String Symbols, Substrings, and Expressions 


A string constant is a string of any printable characters 


enclosed by quotation marks. Empty strings are also permitted. 
The number of characters cannot exceed 132 (decimal). For 
example: 

"ABCDEF" 
String symbols may have the value of any string constant. The 


value is assigned by a .SETS or .ASKS directive. For example, 
the directive statements: 


SETS S1 "ABCDEF" 
ob S SZ opel 


assign string symbol S2 the value of string symbol S1 (that is, 
ABCDEF). 


A substring facilitates the extraction of a segment from _ the 
value of a string symbol. You can use substrings only in second 
operands of .SETS and .IF directives. For example, the directive 
statements: 


~-SETS $1 "ABCDEF" 
~-SETS S2 Si [123] 


assign string symbol S2 the value of string symbol S1 beginning 
at character one and ending at character three (that 1s, ABC). 


You can also use the syntax [n:*] to extract the characters from 
position n to the end of the string. For example, the directive 
statements: 


-SETS S1 “ABCDEF" 
-SETS S2 S81[3:*] 


assign string symbol S2 the value "CDEF". 


SYMBOLS 


You can combine a string constant, symbol, or substring with 
another string constant, symbol, or substring by the string 
concatenation operator (+) to form a string expression. 


String expressions are permitted as second operands in .SETS' and 
-IF directives where the first operand is a string symbol. For 
example, the directive statements: 


~SETS op "AN 
-SETS SZ “CDER™ 
~oETS S3 S1+"B"+S2[1:3] 


assign string symbol S3 the value of the concatenation of string 
symbol S1, string constant "B", and the first three characters of 
string symbol S2 (that is, ABCDE). 


4.4.4 Reserved Symbols 


Parameters for a command file can be passed to Indirect for 
processing. The parameters are stored in the following reserved 
local symbols: 


PO, Pi, PZ, P3, P4, P5, P6, P7, P8, PY, COMMAN 


The symbol COMMAN contains everything in the issuing command 
line, including the specification for the command file itself. 
The symbols PQ through P9 contain individual elements of the 
command line. The elements are delimited by spaces. 


With the .GOSUB directive any parameters to the right of the 
label and to the left of a comment are transferred to the symbol 
COMMAN. The value of COMMAN can then be parsed to obtain formal 
call parameters. 


4.4.5 Symbol Value Substitution 


Substitution can occur in any command line. Indirect can use the 
values assigned to logical, numeric, string, or special symbols 
by replacing a normal parameter (for example, a device unit) with 
the symbol name enclosed in apostrophes (for example, 'DEV’). 
When a previous directive has enabled substitution mode (.ENABLE 
SUBSTITUTION), Indirect replaces the symbol name enclosed in 
apostrophes with the value assigned to the symbol. 


When Indirect encounters an apostrophe, it treats the subsequent 


text, up to a second apostrophe, as a symbol name. Indirect then 
searches the table of symbols for the corresponding symbol and 
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substitutes the value of the symbol in place of the symbol name 
and surrounding apostrophes in the command line. 


For example, the first three lines in the following example 
appear in an indirect command file. When the processor executes 
these lines, it displays the last two lines at the entering 
terminal’s screen. 


ASKS DEV MOUNT ON DEVICE? 
-ENABLE SUBSTITUTION 
MOUNT 'DEV’ 


S * MOUNT ON DEVICE? [S]: DZ2: 
S MOUNT DZ2: 


DZ2: was entered in response to the displayed question. This 
reply assigned the string value DZ2: to string symbol DEV. Then 
when Indirect read: 


MOUNT ‘DEV’ 


it substituted for 'DEV’ the value assigned to DEV (that is, 
DAZ.e \x Tf substitution mode was not enabled, Indirect would 
Simply have passed the line to DCL as it appeared in the command 
file (that is, MOUNT ’DEV’). 


If substitution mode is enabled (it is enabled by default, if you 
have not disabled it), an apostrophe signals the beginning of a 
String symbol. Thus, to include a single quote as text within a 
command line (rather than as the start of a symbol), you must 
replace the single quote with two contiguous apostrophes ('’’). 


If substitution mode is enabled, Indirect displays the following 
command file line: 


! DON’’T SHOOT 
as 


!. DON’T. SHOOT 


4.4.5.1 Substitution Format Control - The conversion of numeric 
values to strings and the placement of string and logical values 
in a substitution operation can be controlled with a format 
control string. The control string is in the following form: 


..-.’symbol%controlstring’... 


SYMBOLS 


The control string begins with the percent sign (%) and ends with 
the second of the two apostrophes that denote the substitution 
operation. The control string consists of one or more of the 
following characters: 


C Compress leading, embedded, and trailing blanks, and 
remove embedded nulls. 


D Force the conversion of a numeric symbol to decimal. 
O Force the conversion of a numeric symbol to octal. 

S Perform signed conversion for a numeric symbol. 

M Perform magnitude conversion for a numeric symbol. 

Z Return leading zeros for a positive numeric value. 


Rn Right-justify the resulting string, truncating to ‘n’ 
decimal characters if necessary. 


Ln Left-justify the resulting string, truncating to ‘n’ 
decimal characters if necessary. 


X Convert the variable to Radix-50 characters. 

V If the symbol being substituted is numeric, convert the 
low byte to its equivalent ASCII character and 
substitute it. 

If the symbol being substituted is a string, convert 
the first character to its octal representation and 
substitute it. 

Indirect does not perform a consistency check on the control 


string. Tf ‘you specify conflicting format characters, Indirect 
uses the last one specified. 


4.5 SWITCHES 
The indirect command processor accepts five switches: /TR, /DE, 
Jf/CLly SLB, and: (LO: 


Switch Function 


/([NO]JTR Displays a trace of the indirect command file on the 
screen. This function is useful for debugging an 
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/(NO]DE 


/([NO]CLI 


/UB 


SWITCHES 


indirect command file. Each command line, including 
Indirect directive statements, is displayed. The 
default is /NOTR. 


Indicates that the indirect command file is to be 
deleted when its processing is complete unless a 
logical end-of-file (/) or . STOP directive is 
encountered before the end of the file. The default is 
/NODE. 


Passes commands not processed by Indirect to DCL. The 
default is /CLI. 


Indicates that the specified file is a universal 
library of command procedures and that the specified 
module.1s. the procedure’ to be executed. 


When command procedures, which are indirect command 
files, are inserted into a universal library with the 
Librarian command, you can subsequently reference them 
with /LB:module. 


Command libraries are built by creating a universal 
library and inserting command files into it. You can 
then reference the procedures in the library with the 
following command line: 


@command-library/LB:module 
The default file type for a command library is .CLB. 


If you do not specify a module (@command-library/lb), 
Indirect attempts to locate a module called .MAIN.. 


See the example below. 


The command file PARAM. CMD contains parameter 
definitions for the .SETN directive and the command 
file SYSPRC.CMD contains system-specific procedures. 
Use the following command lines to create the command 
library and enter the command files into it: 


S LIBR/CREATE/UNIVERSAL SYSTART.CLB 
S LIBR/INSERT SYSTART.CLB PARAM. CMD 
S LIBR/INSERT SYSTART.CLB PROCED.CMD 
You can then use the following command lines’ to 


reference the command library modules: 


RAM ‘Define global symbol 


@SYSTART/LB: PA 
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@SYSTART/LB:PROCED !Run init procedure 


DIGITAL supplies a library of command procedures. The 


library 


is LB:[{1,2]INDSYS.CLB and it contains’ the 


following procedures: 


INDCFG 


INDDMP 


INDPRF 


INDSFN 


INDVFY 


QIOERR 


FMSDEM 


Displays the current build parameters for the 
running Indirect task. 


@LB:[{1,2]INDSYS/LB: INDCFG 


Dumps to the screen the contents of the 
Indirect symbol table. 


@LB:[1,2]INDSYS/LB: 


INDDMP/LO 


A sample procedure to fully parse file-name 
strings. 


To return a parsed string in <EXSTRI>D: 


@LB:[(1,2]INDSYS/LB: IND 


PREF DW 


1:[DATA]st.dat;2 
Returns system configuration information. 


To return in <EXSTRI> whether the Floating 
Point unit is present: 


Displays the values of all of the _ special 
symbols. 


@LB:(1,2]INDSYS/LB: INDVFY 


Returns a string expansion of the <FILERR> 
error codes. 


To returns in <EXSTRI> a string expansion for 
the code. 


@LB:({1,2]INDSYS/LB:QIOERR -33. 


Demonstrates the PRO/FMS interface 
incorporated into Indirect. 


See the description of the .FORM command. 


SWITCHES 


. MAIN Demonstrates how to use the command library. 
@LB:[{1,2]INDSYS/LB 


. INDEX Displays an index of the procedures in the 
library. 


@LB:{1,2]INDSYS/LB: . INDEX 
The following command line shows the format 
for invoking a command procedure in the 
Library: 
@LB:[1,2]INDSYS/LB:procedurename 

/([NO]LO Indicates that when a new command file is executing, it 


can have access to the local symbols created by its 
calling command file. The default is /NOLO. 


4.6 USING INDIRECT DIRECTIVES 
Directives must be separated from their arguments and from 
DCL-specific commands by at least one space. Only one directive 


per command line is allowed. 


You can insert any number of blanks and horizontal tabs in three 
places of a command line: 


@e At the start of the command line 

@e Immediately following the colon (:) of a label 

@ At the end of the command line 
This allows you to format the command files for readability. The 


recommended procedure is to begin labels in column one and 
everything else in column nine (after one horizontal tab). 


USING INDIRECT DIRECTIVES 


An important exception is the lines processed between .ENABLE and 
-DISABLE DATA directives; no blanks or tabs are removed from 
these lines. For example: 


-LFT Z .GOTO 10 
MACRO/NOLIST TEST 
10: LINK TEST 
~-OPEN DATFIL 
~-DATA XXXXX 
-ENABLE DATA 
This is data 
that goes into 
the data file. 
~-DISABLE DATA 
~GOTO 20 


Note that the .DISABLE DATA statement must begin in column i or 
Indirect will place it in the data file. 


4.6.1 Logical Tests 

A number of .IF directives make tests; if the test is true, 
Indirect processes the remainder of the command line. Logical 
tests can be combined to form compound logical tests by using the 
-AND and .OR directives. 


An implied .AND is effected when more than one .IF appears on the 
same line without being separated by an .AND directive. 


When using .AND and .OR, the .AND directive takes precedence over 
the .OR directive, as shown in the following example: 


bE A 2©OR. «DPT B. «AND «fF T C..GOrO .D 
That is, Indirect reads the line as: 

-L[FT A .OR (.IFT B .AND .IFT C) .GOTO D 
Examples follow: 

~-IFT A .AND .IFF B .GOTO HELP 


If the logical symbol A is true and the logical symbol B is 
false, control passes to the line containing the label .HELP:. 


-LFT A .IFF B .GOTO HELP 


Same effect as the previous directive (.AND implied). 


USING INDIRECT DIRECTIVES 


-IFT A .OR’ .IFF B RUN TESTER 


If the logical symbol A is true or if the logical symbol B is 
false, the RUN command is issued. 


The following sections describe all of the Indirect directives. 


/ - DEFINE LOGICAL END-OF-FILE 


4.7 / - DEFINE LOGICAL END-OF-FILE 


The logical end-of-file directive (/) terminates file processing 
and exits. The message 


S$ @ <EOF> 
is then displayed. 
Format 

7 
is the first nonblank character on a line. 
You can use this directive at any location in the command file to 
quickly terminate file processing, but care should be taken to 
avoid an inadvertent exit. 


Example 


-ASK CONT DO YOU WISH TO CONTINUE 
.IFT CONT .GOTO 100 


A 
-100: 


-ASK - ASK A QUESTION AND WAIT FOR A REPLY 
4.8 .ASK - ASK A QUESTION AND WAIT FOR A REPLY 


The .ASK directive prints a question on the screen, waits for a 
reply, and sets a specified logical symbol to the value of true 
or false, depending on the reply. If the symbol has not already 
been defined, Indirect makes an entry in the symbol table. If 
the symbol has been defined, Indirect resets its value (true or 
false) in accordance with the reply. Indirect exits with a fatal 
error if the symbol was previously defined as a string or numeric 
symbol. 


Formats (brackets are required syntax) 


-ASK ssssss txt-strng 
-ASK [default:timeout] ssssss txt-strng 
-ASK [:timeout] ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
true or false value. 


txt-strng The question or prompt that Indirect displays. 


default The default response; used if the question 1s 
answered with an empty line (null) or if timeout 
occurs. The default can be <TRUE> or <FALSE> or 
another logical variable. 


timeout The timeout count. Indirect waits this long for 
a response, then applies the default answer. 
The format for timeout is nnu, where nn is_ the 
decimal number of time units to wait and u is § 
(seconds), M (minutes), or H (hours). The 
timeout count is used only if timeout mode is 
enabled (.ENABLE TIMEOUT). 


The entire .ASK statement must fit on one command line. 


Note that if you omit the default value but specify a timeout 
count, the colon is required for positional identification. 


When executing an .ASK directive, Indirect displays txt-strng 
prefixed by an asterisk and suffixed with "? [Y/N]:". Indirect 
recognizes five answers: 


1. Y<RET> 


Set symbol ssssss to true. 


4-28 


-ASK - ASK A QUESTION AND WAIT FOR A REPLY 


2. N<RET> 
Set symbol ssssss to false. 
3:4 <RET> 


Set symbol to false or to user-specified default value. 
<RET> indicates the <RETURN> key. 


4. <ESC> 
Set symbol ssssss to true and set the special logical 
symbol <ESCAPE> to true only if escape recognition has 
been enabled. <ESC> indicates the <ESCAPE> key. 
NOTE 
If escape sequence recognition is not enabled, 
the <Fi1l> key (ESC) functions as the escape key 


Ss. <CTRE/Z> 


If CONTROL-Z mode is enabled, set <EOF> to true and 
proceed, or else exit immediately. 


Example 
The directive statement: 
-ASK INSFOR DO YOU WANT TO INSTALL FORTRAN 
displays 
S * DO YOU WANT TO INSTALL FORTRAN? [Y/N]: 
on the screen. Symbol INSFOR will be set to true or false after 


you type yY, N, the <RETURN> key, or the <ESCAPE> key (if escape 
recognition is enabled). 


-ASKN - ASK FOR DEFINITION OF A NUMERIC SYMBOL 
4.9 .ASKN - ASK FOR DEFINITION OF A NUMERIC SYMBOL 


The .ASKN directive prints on the terminal screen a request for a 
numeric value, waits for it to be entered, optionally tests the 
range for the numeric response and/or applies a default value, 
and sets the specified symbol accordingly. 


If the symbol has not previously been defined, Indirect makes an 
entry in the symbol table. If the symbol has already been 
defined, Indirect resets its value in accordance with the reply. 
Indirect exits with a fatal error if the symbol was previously 
defined as a logical or string symbol. 
Formats (brackets are required syntax) 


-ASKN ssssss txt-strng 
-ASKN [low:high:default: Gaeone) ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
numeric value. 


txt-strng The question or prompt that Indirect displays. 


low:high A numeric expression giving the range for’ the 
response. 
default A numeric expression or symbol giving the 


default value. 


timeout The timeout count. Indirect waits this long for 
a response, then applies the default answer. 
The format for timeout is nnu, where nn is’~ the 
decimal number of time units to wait and u is §S 
(seconds), M (minutes), or H (hours). The 
timeout count is valid only if timeout mode is 
enabled (.ENABLE TIMEOUT). 


The entire .ASKN statement must fit on one command line. 


Note that if you omit any of the parameters within the square 
brackets, any preceding colons are required for positional 
identification. 


The command line cannot exceed 132 (decimal) characters in 
length. When executing an  .ASKN directive, Indirect displays 
txt-strng prefixed by an asterisk and suffixed with [0]: to 
indicate that the response is considered as octal or [D]: to 
indicate that the response is considered as decimal. The reply 
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must be a number either within the specified range or in the 
range 0 through 177777 (octal) (by default) or 0 through 65535 
(decimal). : 
If the response is outside the specified range, the message 

IND -- VALUE NOT IN RANGE 
is displayed and the query repeated. 
If an arithmetic operation yields a result greater than 177777 
(octal) when computing the actual value of any of the arguments 
(low, high, or default), a fatal error occurs and the message 

IND ~~ NUMERIC UNDER- OR OVERFLOW 
is displayed. 
If the response is an empty line (null) and a default value 
(default) was not specified, Indirect applies a default of 0. 
Note that in this case, the range, if specified, must include 0. 
The response may be either octal or decimal; a leading pound sign 
(#) forces octal, a trailing period (.) forces decimal. In the 
absence of both, Indirect applies a default radix. The default 
radix is decimal if either the range or default values are 
decimal expressions (followed by a period). Otherwise, the 
default radix is octal (unless decimal mode has been enabled). 
Indirect displays the default type as either [0] or [D]. 


To force a default decimal radix without specifying a range 
argument, use the following construction: 


~-ASKN [::0.] A ENTER VALUE 
or 


-ENABLE DECIMAL 
-ASKN A ENTER VALUE 


Examples 
@® The directive statement: 
-ASKN SYM DEFINE NUMERIC SYMBOL A 
displays 
S * DEFINE NUMERIC SYMBOL A [O]: 


on the terminal screen where: 
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[O] 1s the default radix (octal). 


Indirect then defines symbol SYM according to the reply 
entered. 


The directive statement: 

-ASKN [2:35:16:20S] NUMSYM DEFINE NUMERIC SYMBOL A 
displays 

S * DEFINE NUMERIC SYMBOL A [O R:2-35 D:16 T:20S]: 
in the format [x R:low-high D:default T:timeout] 


where: 


x O if the default radix is octal or D if 
it is decimal. 


R:low-high The specified range. 


:default The specified default. 


) 


T:timeout The specified timeout count before the 
default answer is applied. 


Indirect then checks that the response string is in the 
specified range. 


The directive statement: 
-ASKN [NUMSYM+10:45:NUMSYM+10] SYM DEFINE NUMERIC SYMBOL 
displays (assuming the value of 16 octal for NUMSYM): 


S * DEFINE NUMERIC SYMBOL B [O R:26-45 D:26]: 


ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


4.10 .ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


The .ASKS directive prints on the terminal screen a request for a 
string value to define a specified symbol and optionally tests 
that the number of characters in the response string falls within 
the specified range. 


If the symbol has not previously been defined, Indirect makes an 
entry in the symbol table. If the symbol has already been 
defined, Indirect resets its value in accordance with the reply. 
Indirect exits with a fatal error if the symbol was defined 
previously as a logical or numeric’ symbol. If the number of 
characters is out of the specified range, the message 

IND -- STRING LENGTH NOT IN RANGE 
is displayed and the question repeated. 


Formats (brackets are required syntax) 


-ASKS ssssss txt-strng 
-ASKS [low:high:default:timeout] ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
string value. 


txt-strng The question or prompt that Indirect displays. 


low:high A numeric expression giving the range for the 
number of characters permitted in the response 
string. 

default A string expression or symbol giving the default 
value. 

timeout The timeout count. Indirect waits this long for 


a response, then applies the default answer. 
The format for timeout is nnu, where nn is’ the 
decimal number of time units to wait and u is S 
(seconds), M (minutes), or H_ (hours). The 
timeout count is valid only if timeout mode is 
enabled (.ENABLE TIMEOUT). 


The entire .ASKS statement must fit on one command line. 
Note that if you omit any of the parameters within the square 


brackets, any preceding colons are required for positional 
identification. 


ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


When executing an .ASKS directive, Indirect displays txt-strng 
prefixed by an asterisk (*) and suffixes it with [S]J:. The reply 
must be an ASCII character string. 


Examples 
e The directive statement: -ASKS NAM PLEASE ENTER YOUR NAME 
displays 


S$ * PLEASE ENTER YOUR NAME [S]: 


on the terminal screen. Indirect then defines symbol NAM 
according to the string reply entered. 


The directive statement: 
-ASKS [1:15::10S] MIDNAM PLEASE ENTER YOUR MIDDLE NAME 
displays 
S * PLEASE ENTER YOUR MIDDLE NAME [S R:1-15 T:10S]: 
in the format [S R:low-high T:timeout] 
where: 
S The symbol type (string). 


R:low-high The specified range _ for number of 
characters. 


T:timeout The specified timeout count. 


-BEGIN - BEGIN BLOCK 


4.11 .BEGIN - BEGIN BLOCK 


The .BEGIN directive marks the beginning of a Begin-End block. 
The block must be terminated with an .END directive. 


Labels and local symbols defined following the .BEGIN directive 
are local to the block instead of being used throughout the 
entire command file. Therefore, labels and local symbols defined 
inside a block lose definition outside the block. (Labels and 
symbols defined outside a block retain definition throughout’ the 
File.) Labels and symbols defined outside a block and then 
modified within the block, however, assume and retain the value 
assigned in the block. 


Labels and local symbols defined within a block lose definition 
with an .ERASE LOCAL directive statement or with the .END 
directive. 
-BEGIN must be the only directive on a command line. For 
example, the .BEGIN directive cannot appear on the same line as 
an .IF directive. 
Format 

. BEGIN 


as the only directive on the line. 


~CHAIN - CONTINUE PROCESSING USING ANOTHER FILE 


4.12 .CHAIN - CONTINUE PROCESSING USING ANOTHER FILE 


The .CHAIN directive closes the current file, erases all local 
symbols, clears any .ONERR arguments, empties the direct access 
label cache, and continues processing using command lines’ from 
another file. However, the .CHAIN directive does not close data 
files or change the nested-file level. 
Format (brackets not part of syntax) 

-CHAIN filename[/switches] 
where filename is the name of the file that contains the new 
command lines. The /switches are any of the optional switches 
described in Section 4.5. 
Example 
The directive statement: 


.CHAIN OUTPUT 


transfers control to the file OUTPUT.CMD. 


-CLOSE - CLOSE SECONDARY FILE 


4.13 .CLOSE - CLOSE SECONDARY FILE 


The .CLOSE directive closes the secondary file opened by an .OPEN 
directive. 


Format (brackets not part of syntax) 


.CLOSE [#n] 

where: 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric symbol 
for the value n by enclosing the symbol in 

: apostrophes. 


-DATA - OUTPUT DATA TO SECONDARY FILE 


4.14 .DATA - OUTPUT DATA TO SECONDARY FILE 


The .DATA directive specifies text that is to be output to a 
secondary file previously opened by an .OPEN directive. 


When Indirect processes the text string that follows the .DATA 


directive, it 


ignores a leading space (if present), assuming it 


to be a separator between the directive and the text string. Any 
other spaces or tabs are transferred to the data file. 


Format (brackets not part of syntax) 


.DATA [#n] 

where: 
txt-strng 
#n 


The command line 
specified text 


txt-strng 


The text to be output to the secondary file. 


An optional file number in the range 0 to 3. 
The default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol 
in apostrophes. 


cannot exceed 132 (decimal) characters and the 
string cannot continue onto the next line. If a. 


secondary file is not open, an error condition exists; Indirect 
issues an error message and begins error processing. 


Example 


-SETS SEND 
-OPEN TEMP 


~-DATA ‘SEND’ 


CLOSE 


These directives 


"THIS IS DATA" 


output THIS IS DATA to. the secondary file 


TEMP.DAT (.DAT is the default file type for a data file). 


~-DEC - DECREMENT NUMERIC SYMBOL 


4.15 .DEC - DECREMENT NUMERIC SYMBOL 


The .DEC directive decrements a numeric symbol by one. Indirect 
exits with a fatal error if the symbol was defined previously as 
a logical or string symbol. 

Format 


-DEC SSSSSS 


where: 

SSSSSS The 1- to 6-character numeric symbol. 
Example 

-DEC LOOPCT 


This directive decrements by 1 the value assigned to the numeric 
symbol LOOPCT. 


.DELAY - DELAY EXECUTION FOR A SPECIFIED PERIOD OF TIME 


4.16 .DELAY - DELAY EXECUTION FOR A SPECIFIED PERIOD OF TIME 


The .DELAY directive delays further processing of the file for a 
specified period of time. 


Format 
»-DELAY nnu 
where: 
nn The decimal number of time units to delay. 
u S - seconds 
M - minutes 
H - hours 


The parameter nn is decimal by default. 


If quiet mode is disabled when the .DELAY directive is executed, 
Indirect issues the message: 


IND -- DELAYING 


When the time period expires and the task resumes, Indirect 
issues the message: 


IND -- CONTINUING 
Example 
The directive statement: 
.DELAY 20M 


delays processing for 20 (decimal) minutes. 


.DISABLE - DISABLE OPTION 


4.17 .DISABLE - DISABLE OPTION 
The .DISABLE directive disables a specified operating mode 
previously activated by an .ENABLE directive. 
Format 
.DISABLE option[,option...] 


The following is a list of the operating modes that can _ be 
disabled: 


ATTACH DETACH GLOBAL TIMEOUT 
CONTROL-Z DISPLAY LOWERCASE TRACE 

DATA ESCAPE CLI TRUNCATE 
DECIMAL ESCAPE-SEQ OVERFLOW SUBSTITUTION 
DELETE QUIET 


Note that when you disable detach mode from a command file and 
then request a task or DCL command to display information, the 
command file may not be able to continue executing. The task or 
DCL command may need to attach to the terminal to display the 
information but will not be able to do so because Indirect cannot 
detach from the terminal. 


-ENABLE - ENABLE OPTION 


4.18 .ENABLE - ENABLE OPTION 


The .ENABLE directive is used to invoke several operating modes. 
Each mode is independent of the others; all of them can be active 
Simultaneously. When Indirect starts to process a file, the 
initial settings are: 


ATTACH enabled GLOBAL enabled 
CONTROL-Z disabled LOWERCASE enabled 
DATA disabled CLI enabled 
DECIMAL disabled OVERFLOW disabled 
DELETE disabled QUIET disabled 
DETACH enabled SUBSTITUTION enabled 
DISPLAY enabled TIMEOUT enabled 
ESCAPE disabled TRACE disabled 
ESCAPE-SEQ disabled TRUNCATE disabled 


In attach mode, Indirect attaches to the screen when displaying 
comment lines. In detach mode, it detaches from the screen when 
processing command lines. Enabling both of these modes allows 
you to type CTRL/O to suppress a lengthy comment. 


Enabling Control-Z mode allows a command file to detect a CTRL/Z 
response to a question and continue processing. If Control-Z 
mode is disabled and you type CTRL/Z in response to an_  .ASKx 
question, Indirect exits. If Control-Z mode is enabled, the 
Special symbol <EOF> is set to true and Indirect continues 
processing the command file. 


In data mode, Indirect outputs lines that follow an .ENABLE DATA 
directive statement to a secondary file. (The .DATA directive 
sends a single line of text to a secondary file.) To disable data 
mode, the .DISABLE DATA statement must begin in the first column. 
Otherwise, Indirect copies the statement itself into the data 
file. The .ENABLE DATA directive also has an optional argument 
(#n) that specifies which file the data is to go into. See the 
description of the .DATA directive for more information. 


In global symbol mode, symbol names that begin with a dollar sign 
(S$) are defined as global to all levels of indirect files; once 
such a symbol has been defined, all levels recognize it. Symbols 
that do not begin with a dollar sign are recognized only within 
the level that defines them. 


In decimal mode, all numeric symbols are created or redefined by 
default as decimal instead of as octal. 


In delete mode, the current command file is deleted when Indirect 
processes the last command line in the file. 
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In display mode, Indirect displays the current fields for’ the 
-ASKx directives and @ <EOF>. If display mode is disabled, 
Indirect displays only the text string for the .ASKx directive 
and suppresses @ <EOF>. 


In CLI mode, commands not processed by Indirect are passed _ to 
DCL. CLI mode is equivalent to the functions of the /CLI switch. 


In lowercase mode, characters read from the terminal in response 
to .ASKS directives are stored in the string symbol without 
lower- to uppercase conversion. The representation of characters 
is significant when comparing strings since the .IF directive 
distinguishes between lowercase and uppercase characters. 


In substitution mode, Indirect substitutes a string for a symbol. 
The symbol must begin and end in apostrophes (’symbol’). For 
example, if the symbol A has been assigned the string value THIS 
IS A TEST, then every ‘A’ will be replaced by THIS IS A TEST. | 
When substitution mode 1s enabled, Indirect performs 
substitutions in each line before scanning the line _ for 
directives and DCL commands. 


Escape recognition (.ENABLE ESCAPE) permits the response to an 
-ASK, -ASKN, or .ASKS directive to be an escape character. A 
question answered with a single escape character sets the special 
logical symbol <ESCAPE> to true. The escape character must be 
used only as an immediate terminator to the question; if one or 
more characters precede the escape character, an error condition 
exists. In this case, the message 


IND -- INVALID ANSWER OR TERMINATOR 


is printed and the question repeated. Note that if you press the 
<ESCAPE> key in response to an .ASK directive, the specified 
logical symbol (ssssss of .ASK ssssss txt-strng) is also set to 
true. 


Escape-sequence recognition (.ENABLE ESCAPE-SEQ) forces Indirect 
to attach to the terminal for escape-sequence recognition, using 
the IO.ATT!TF.ESQ 1/0 function. 


In this mode, the result of an .ASKx or .READ statement from the 
terminal will contain the terminating escape character and escape 
sequence, as documented in the P/OS System Reference Manual. 


Overflow mode allows signed arithmetic in numeric expressions. 
Enabling the mode provides for numeric expressions and operations 
that otherwise would result in the "Numeric under- or overflow" 
error message. 


In quiet mode, Indirect does not echo DCL command lines or 
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comments. The command lines are executed normally and, if they 
return a message or display, the message or display is printed on 
the screen. 


In timeout mode, Indirect uses the timeout parameters specified 
with the .ASKx directives. Indirect waits for the timeout count 
to elapse and then applies the default answer to the directives. 
Timeout mode must be enabled (the default) to use the timeout 
counts for the .ASKx directives. 


In trace mode, command lines that Indirect has processed are 
displayed on the terminal screen. As each line is processed, it 
is displayed with its nesting level and an exclamation mark (!). 
Trace mode is equivalent to the function of the /TR switch. 


In truncate mode, Indirect ignores any truncate errors on a .READ 
directive. A truncate error occurs when a line ina file is too 
long. If the full record cannot ep within the 132 
(decimal)-character limit of the symbol, the record is truncated. 
Formats (brackets not part of syntax): 

.ENABLE option[,option...] 


.ENABLE DATA [#n] 


where: 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric symbol 
for the value n by enclosing the symbol in 
apostrophes. 

Examples 


@ Substitution mode: 


-ENABLE SUBSTITUTION 
~-ASKS FIL SPECIFY SOURCE FILE 
MACRO ‘FIL’ 


When the file is executing, the corresponding lines displayed 
at the terminal screen are: 


S * SPECIFY SOURCE FILE [S]: SOURCE 
S MACRO SOURCE 


.ENABLE - ENABLE OPTION 


e cControl-Z mode: 


-ENABLE CONTROL-Z 

-ASK RESP DO YOU WISH TO CONTINUE 
-IFT <EOF> .GOTO CLENUP 

-IFF RESP> .GOTO CLENUP 


If you type CTRL/Z in response to the question, <EOF> is set 
to true and Indirect transfers to CLENUP. 


-END - END BLOCK 


4.19 .END - END BLOCK 


The .END directive marks the end of the Begin-End block. TE 
Indirect encounters more .END directives than .BEGIN directives, 
command processing terminates and the following message is 
displayed: 

IND -- ILLEGAL NESTING 
Format 

- END 


as the only directive on the line. 


-ERASE - DELETE SYMBOLS 


4.20 .ERASE - DELETE SYMBOLS 


The .ERASE directive deletes all local or global symbol 
definitions, or a specific global symbol definition. When you 
define a symbol, either locally (by defining a symbol value) or 
globally (by enabling global symbol mode and preceding the symbol 
name with a dollar sign ($)), Indirect creates an entry in the 
symbol table. The .ERASE directive erases either all local or 
all global entries, or a specific global entry, in the table. 


Following an .ERASE directive, you can redefine symbol values as 
well as symbol type. 


Formats 
»-ERASE LOCAL 
-ERASE GLOBAL 
~-ERASE SYMBOL global-symbol 


An .ERASE LOCAL directive outside of a Begin-End block erases all 
local symbols defined within the current file. 


An .ERASE LOCAL directive within a Begin-End block erases’ only 
those local symbols defined within the block. 


However, note that the following actions also occur: 


1. Local symbols defined within a nested file are erased 
when that file exits... 


2. Local symbols defined within a Begin-End block are 
erased with .END. 


3. Local symbols defined outside of Begin-End blocks are 
visible, modifiable, and not erasable within a Begin-End 
DLOCK. 


An .ERASE GLOBAL, either outside of or within a Begin-End block, 
erases all global symbols. 


An .ERASE SYMBOL global-symbol erases the specified global 
symbol. (Individual local symbols are not erasable.) 


»~-ERASE - DELETE SYMBOLS 


Example 
.ERASE LOCAL 


This directive erases all local symbol definitions used in the 
indirect command file. 


-ERASE SYMBOL SSWITC 


This directive erases the single global symbol "SSWITC." 


~-EXIT - EXIT CURRENT COMMAND FILE 


4.21 .EXIT - EXIT CURRENT COMMAND FILE 


The .EXIT directive terminates processing of the current command 
file or Begin-End block and returns control to the previous-level 
command file or, if the directive is executed within a block, to 
the line following the .END directive. If the directive is 
encountered at the uppermost indirect nesting level, Indirect 
exits and passes control to DCL (see the .STOP directive). 


The .EXIT directive also allows you to optionally specify a value 
to copy into the special symbol <EXSTAT>. 


Format (brackets not part of syntax) 
~-EXIT [value] 
where value is an optional numeric expression copied to <EXSTAT>. 
Examples 
The following line is in an indirect command file called TEST1: 
@TEST2 
The file TEST2.CMD contains the following line: 
EXIT 


When Indirect encounters the .EXIT directive in TEST2, control 
returns to TEST1.CMD. 


If the .EXIT directive in TEST2.CMD includes a numeric 
expression, for example: 


~EXIT N+2 


Indirect evaluates the expression and copies the value into 
<EXSTAT>D. 


~-FORM - ACCESS FORM DRIVER 


4.22 .FORM - ACCESS FORM DRIVER 


The .FORM command provides access to the PRO/FMS-11 form driver 
from a command file. You can specify commands in the command 
file that perform operations such as: 

@e Directing the display of a form 

@® Directing the motion of the cursor from field to field 

@® Acquiring and parsing the user typein 
The syntax of the .FORM command parallels the format of the 
MACRO-11 call interface to FMS-11. For details, see the 
FMS-11/RSX Software Reference Manual, particularly the chapters 
on form driver operation and the MACRO-11 interface. 


Format 


«FORM FNC; pL; p2;4<4>pn 


where: 

FNC is a three-letter code indicating which FMS 
operation is to be performed. These codes 
are a subset of the codes used in the 
MACRO-11/FMS interface and are summarized 
below. 

Dives pn are string or numeric symbols or constants 


conforming to Indirect syntax rules. 


Formal parameters: 


LINENUM The screen line number where form display is 
to begin. 
RETTRM The name of a numeric variable to contain the 


code for the terminator typed by the user. 


FILENAME The name of a string variable or string 
constant naming the file in which the form 
definitions are stored. 


RETNAM The name of the field completed by the user. 
RETINX The index of the field completed by the user. 
TERMINATOR The code for the terminator to be processed. 
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VALUE A string variable or constant to be placed in 
the indicated field. 


FORMNAME The name of the form to display. 


FLDNAME The name of a field defined in the currently 
displayed form. 


INDEX In an indexed field, the index referencing 
the specific field being addressed. 


RETVAL The name of a string variable into which the 
returned value will be placed. 


Examples 


String values supplied as input to the .FORM command can _ be 
expressed as a constant enclosed in quotation marks or as the 
name of a previously defined string variable. For example, the 
following have equivalent results: 


-FORM OPN, "FMSDEM.FLB" 'define form library filename 
and 


.SETS LIBR "FMSDEM.FLB" 
.-FORM OPN,LIBR !'define form library filename 


String and numeric values returned as output from the .FORM 
command are passed as though a .SETS or .SETN command were being 
executed. This means that the name of the variable to receive 
the value must be supplied, and that it must either have not been 
defined or is previously defined as the appropriate string or 
numeric type. For example: : 


~FORM GET, "CHOICE",,,,FLDVAL ! return value of field 
"CHOICE™ 


The Indirect local symbol FLDVAL is defined or redefined as 
required and contains the string typed by the user to fill the 
field named CHOICE on the currently displayed form. 


Remember that Indirect can handle strings only as long as 132. 
characters, so that values returned to strings from the form 
driver must be shorter than that length. This is particularly 
important with the ALL and RAL commands, which attempt to place 
the string values of all fields displayed on the form into a 
Single Indirect string variable. A better programming practice 
would be to use a series of GET commands addressing each 
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individual field. 


A demonstration procedure is included in LB:[{1,2]INDSYS.CLB. 
This procedure library is packaged on the PRO/Tool Kit 
distribution kit. To execute the demonstration procedure, type 
the following command line: 


S$ @LB:[1,2]INDSYS.CLB/LB: FMSDEM 


After the terminal type setting is verified, a temporary copy of 
the forms library is placed in your directory. The procedure is 
identical to that provided in MACRO-11 form on the FMS-11/RSX 
kit. Refer to the FMS-11/RSX Software Reference Manual for a 
complete description of this demonstration. 


Using the following DCL command, extract the FMS demonstration 
procedure and use it as an extended example for building your own 
command procedures. 


S LIBRARIAN/EXTRACT/OUT=FDEM.CMD LB:[1,2]INDSYS.CLB FMSDEM 
Commands: 
CSH -- Clear screen and show form 

.FORM CSH, FORMNAME [,LINENUM] 


The form driver clears the entire screen and displays the 
specified form from the currently open form library. If 
LINENUM is supplied, it is interpreted as an integer line 
number which overrides the form starting line number 
supplied by the forms editor. 


SHO -- Show form 
.FORM SHO, FORMNAME [,LINENUM] 


The form driver clears only the portion of the screen 
required for the specified form, then displays the form 
named in FORMNAME from the currently open forms library. If 
LINENUM is present, it overrides the starting line number 
supplied by the forms editor. 


GET -- Get value for specified field 


.FORM GET, FLDNAME [,INDEX [,RETNAM [,RETINX [,RETVAL 
[,RETTRM]]]]] 


The form driver places the cursor at the initial position of 
the specified field and accepts input from the keyboard for 
that field. 
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ANY -- Return any field value 
.FORM ANY ,RETNAM ,[{RETINX] ,RETVAL [,RETTRM] 


The form driver waits for the operator to fill any field. 
The cursor may be positioned in a field that is not 
display-only. The field name and its resulting value are 
returned. | 


ALL -- Return all fields 
.FORM ALL [,RETVAL [,RETTRM] ] 
After the operator has filled any or all fields of a form 
and presses the <ENTER> key, the form driver returns all 
field values as a concatenated string into the string 
variable RETVAL. Remember that strings may have a maximum 
length of 132. characters so that the concatenated value 
may not exceed this length. 

DAT -- Get named data from form 
-FORM DAT, FLDNAME, [INDEX], RETVAL 


The form driver returns the value from the named data 


portion ‘ope the form. If INDEX is supplied, it 1s 
interpreted as the index for the named data value to be 
returned. 

GSC -- Get current line of scrolled area 


~-FORM GSC, FLDNAME, RETVAL [,RETTRM] 


The form driver returns the contents of the entire current 
scrolled data line as a concatenated string. 


CLS -- Close forms library 
»~-FORM CLS 
The currently open forms library is closed. 
OPN -- Open forms library 
-FORM OPN, FILENAME 
The forms driver attempts to open the specified file as a 


library of form definitions. The library is built by the 
forms utility program. 
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PSC -- Put to current line of scrolled area 
-FORM PSC, FLDNAME, VALUE 
The form driver outputs the data specified to the current 
line of the scrolled area. The scrolled area is identified 
by naming in FLDNAME any field in that area. 


TRM -- Process field terminator 


.FORM TRM, [FLDNAME], [VALUE], TERMINATOR [,RETNAM 
[, RETINX] ] 


The user supplies the numeric code for the terminator, 
processed in TERMINATOR. The form driver then performs 


cursor and field positioning accordingly. The FMS-11/RSX 
Software Reference Manual describes terminator codes and 
actions. 

PUT -- Put to specified field 


.FORM PUT, FLDNAME, [INDEX], VALUE 

This displays the value specified in the named field. 
PAL -- Put all fields 

-FORM PAL PE VALUE 


The contents of VALUE are used to fill all fields of the 


current form. Remember that the VALUE string may have a 
maximum of 132. characters. 
LST -- Output to last line of screen 


.FORM LST [,VALUE] 
The form driver clears the last line of the screen and 
displays the specified string. (The last line is not 
normally accessible via a form.) This is the only way to 
display messages in this screen location. 

RAL -- Return all fields 
-FORM RAL, VALUE 

RTN -- Return value for specified field or for all fields 


.FORM RTN, [FLDNAME] , [INDEX], RETVAL 


If the FLDNAME parameter is not present the form driver 
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-FORM - ACCESS FORM DRIVER 
returns the concatenated string of the current values for 
all fields in the form. See the note under the ALL command. 
If FLDNAME is present, the form driver returns the value 
only for the named field. 
SPN/SPF -- Supervisor mode control 


-FORM SPN 
-FORM SPF 


Turn supervisor mode on (SPN) or off (SPF). The form editor 
permits defining some fields as display only if supervisor 


mode is off. 


.GOSUB - CALL A SUBROUTINE 
4.23. .GOSUB - CALL A SUBROUTINE 


The .GOSUB directive saves the current position in an indirect 
command file and then branches to a label. The label identifies 
an entry point to a subroutine that is terminated by a  .RETURN 
directive. 


When you issue a .GOSUB directive from within a Begin-End block, 
Indirect saves the current block context and then scans down the 
file searching for the first occurrence of the subroutine label. 
Note that during the scan, Indirect ignores any intervening 
~-BEGIN or .END directives. The .RETURN directive restores 
previous block context. Thus, the subroutine can be contained 
within a Begin-End block. 


The maximum nesting depth for subroutine calls is 8. 
Format 

.GOSUB label parameters 
where label is the label that designates the first line of a 
subroutine, but without the leading period and trailing colon. 
Any parameters to the right of the label and to the left of a 
comment are transferred to the reserved local symbol COMMAN. The 
value of COMMAN can then be parsed with the .PARSE directive to 
obtain formal call parameters. 
Example 
The directive statement: 


-~GOSUB EVAL 


transfers control to the subroutine labeled .EVAL:. 


-GOTO - BRANCH TO A LABEL 


4.24 .GOTO - BRANCH TO A LABEL 


The .GOTO directive causes a branch from one line in an indirect 
command file to another. All commands between the .GOTO 
directive and the specified label are ignored. Branches can _ go 
forward or backward in the file. 


The target of a .GOTO branch from within a Begin-End block must 
be contained in that block. The .GOTO directive cannot branch 
into another block. When Indirect encounters a .GOTO directive 
within a Begin-End block, it searches for the specified label in 
that block. 


Since Indirect only searches the one Begin-End block, you can use 
the same label more than once in a command file. 


Format 
-GOTO label 


where label is the name of the label, but without the leading 
period and trailing colon. 


Example 
The directive statement: 
.GOTO 100 


transfers control to the line containing the label .100:. 


-IF - TEST IF SYMBOL SATISFIES SPECIFIED CONDITION 


4.25 .IF - TEST IF SYMBOL SATISFIES SPECIFIED CONDITION 


The .IF directive compares a numeric or string symbol with 
another expression of the same type to determine if one of 
several possible conditions is true. If the condition is 
satisfied, Indirect executes the remainder of the command line. 


When comparing a string symbol with a string expression, Indirect 
compares the ASCII values of each operand’s characters (from left 
to right) one by one. An operand is considered greater if the 
first nonequal character has a greater value than the 
corresponding character in the other’ operand. Numeric symbols 
are compared strictly on the basis of magnitude. 


Format 


-IF symbol relop expr directive-statement 


where: 
symbol The i- to 6-character numeric or. string 
symbol. 
relop One of the following relational operators: 
EQ or = - Equal to 
NE or <> - Not equal to 
GE or >= - Greater than or equal to 
LE or <= - Less than or equal to 
GT or > - Greater than 
LT or < - Less than 
expr An expression of the same type as symbol. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
~SETS X "A" 
-SETS Y "a" 


.IF X LT Y .GOTO 200 


The ASCII value of string symbol X is less than the ASCII value 
of string symbol Y, which satisfies the less-than condition. 
Thus, control passes to the line containing the label .200:. 


-SETN Ni 2 


-SETN N2 7 
-IF N1 <= N2 DIRECTORY/FULL 


4-58 


-IF - TEST IF SYMBOL SATISFIES SPECIFIED CONDITION 


With the condition satisfied (numeric symbol Ni less than or 
equal to numeric symbol N2), the DIRECTORY command is processed. 


.SETS S1 "AAb" 

.SETS S2 "AA" 

.SETS S3 "BBBB" 

.IF S1 >= S$2+S3[{1:1] .INC N 


The condition is satisfied where string symbol S1 is greater than 
or equal to the concatenation of string symbol S2 and the first 
character of string symbol S3 (AAb >= AAB). Therefore, Indirect 
increments numeric symbol N. 


~-IFACT/.IFNACT - TEST IF TASK IS ACTIVE OR DORMANT 


4.26 .IFACT/.IFNACT - TEST IF TASK IS ACTIVE OR DORMANT 


The .IFACT or .IFNACT directive tests whether a task iS active 
(.IFACT) or dormant (.IFNACT). If the test is true, the rest of 
the command is_ processed. If the specified task is not 
installed, Indirect assumes the dormant condition. 
Formats 

-IFACT taskname directive-statement 


-LFNACT taskname directive-statement 


where: 
taskname A 1i- to 6- character legal task name. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 

Examples 


-ITFACT REPORT .GOTO 350 


-IFNACT REPORT RUN REPORT 


.IFDF/.IFNDF - TEST IF SYMBOL DEFINED OR NOT DEFINED 
4.27 .IFDF/.IFNDF - TEST IF SYMBOL DEFINED OR NOT DEFINED 


The .IFDF or .IFNDF directive tests whether a logical, numeric, 
or string symbol has been defined (.IFDF) or not defined 
(.IFNDF). If the test is true, the rest of the command line is 
processed. This directive does not test the value of the symbol. 


Formats 
-IFDF ssssss_ directive-statement 


-LFNDF sSSSSSS_directive-statement 


where: 
SSSSSS The 1- to 6-character symbol being tested. 
The symbol can be local, global, or an 
Indirect special symbol. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 


-IFDF A .GOTO 100 


-IFNDF A .ASK A DO YOU WANT TO SET TIME 
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-IFINS/.IFNINS - TEST IF TASK INSTALLED OR NOT INSTALLED 


4.28 .IFINS/.IFNINS - TEST IF TASK INSTALLED OR NOT INSTALLED 


The .IFINS or .IFNINS directive tests whether a task is installed 
(.IFINS) or not installed (.IFNINS) in the system. If the test 
is true, the rest of the command line is processed. 

Formats 


-IFINS taskname directive-statement 


-IFNINS taskname directive-statement 


where: 
taskname A i1- to 6-character task name. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
-IFINS ...PIP .GOTO 250 
.IFNINS ...PIP INS DW1:[ZZTKT]PIPRES.TSK 


.ITFENABLED/.IFDISABLED - TEST IF MODE ENABLED OR DISABLED 


4.29 .IFENABLED/.IFDISABLED - TEST IF MODE ENABLED OR DISABLED 


The .IFENABLED or .IFDISABLED directive tests whether an 
Operating mode has been enabled with the .ENABLE directive or 
disabled with the .DISABLE directive. (See the description of 
the .ENABLE directive for the list of operating modes.) 
Formats 

.IFENABLED option directive-statement 


.IFDISABLED option directive-statement 


where: 
option The same operating mode option (with the 
exception of DATA) used with the .ENABLE or 
.DISABLE directive. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
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.IFLOA/.IFNLO - TEST IF DRIVER LOADED OR NOT LOADED 
4.30 .IFLOA/.IFNLO - TEST IF DRIVER LOADED OR NOT LOADED 


The .IFLOA or .IFNLOA directive tests whether a driver is loaded 
(.IFLOA) or not loaded (.IFNLOA) in the system. If the test is 
true, the rest of the command line is processed. For purposes of 
this directive, resident drivers are considered loaded. 
Formats 

.IFLOA dd: directive-statement 


.LFNLOA dd: directive-statement 


where: 
dd: A device driver. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
~IFLOA XK: .GOTO 250 
.IFNLOA XK: ;Sorry, XK Driver not available 


.IFT/.IFF - TEST IF SYMBOL TRUE OR FALSE 
4.31 .IFT/.IFF - TEST IF SYMBOL TRUE OR FALSE 


The .IFT or .IFF directive tests whether a logical symbol is true 
or false. If the test is true, Indirect processes the rest of 
the command line. 


Indirect exits with a fatal error if the tested symbol was 
previously defined as a numeric or string symbol. 


Formats 
-IFT ssssss_ directive-statement 


-IFF ssssss_ directive-statement 


where: 
SSSSSS The 1- to 6-character logical symbol being 
tested. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 


-IFT A  .GOTO 100 


-IFF B  .GOTO 200 


-INC - INCREMENT NUMERIC SYMBOL 


4.32 .INC - INCREMENT NUMERIC SYMBOL 


The .INC directive increments a numeric symbol by one. Indirect 
exits with a fatal error if the symbol was previously defined as 
a logical or string symbol. 
Format 

-INC SSSSSS 


where: 


SSSSSS The 1- to 6-character numeric symbol being 
incremented. 


Example 
.INC B 


Increment by 1 the value assigned to the numeric symbol B. 


.label: - DEFINE A LABEL 


4.33 .label: - DEFINE A LABEL 


Labels always appear at the beginning of the line; they may be on 
a line with additional directives and/or a DCL command, on a line 
with a comment, or on a line by themselves. When control passes 
to a line with a label, the line is processed from the first 
character after the colon. 


Commands do not have to be separated from the label by a = space. 
Only one label is permitted per line. Labels are one through six 
characters in length and must be preceded by a period and 
terminated by a colon. A label may contain only alphanumeric 
characters and/or dollar signs ($). 


It is also possible to define a label as a direct access label; 
once the label is found, its position in the command file is 
saved. This allows subsequent jumps to frequently-called labels 
or subroutines to be effected quickly. The first statement 
processed after a jump to a direct access label is the one on the 
next line. The maximum number of direct access labels you can 
define within an indirect command file is 16. If you define more 
than the maximum number allowed, the subsequent direct access 
labels replace the earliest, and so on. 


To declare a label for direct access, leave the line following 
the colon blank. 


Example 
100% .ASK A DO YOU WANT TO CONTINUE? 
.IFT A .GOSUB 200 


.200: 
~;THIS IS THE START OF A SUBROUTINE 


- RETURN 


-ONERR - BRANCH TO LABEL ON DETECTING AN ERROR 


4.34 .ONERR - BRANCH TO LABEL ON DETECTING AN ERROR 


If Indirect detects one of the errors list below, control passes 
to the line containing the specified label. This feature 
provides you with a means of gaining control to terminate command 
file processing in an orderly manner. 


@e Undefined symbol 

@e Bad syntax 

@ Unrecognized command 

e String substitution error 

e Symbol type error (.IF, .IFT, .IFF, .INC, .DEC) 


@ Redefinition of a symbol to a different type (.ASK, .ASKN, 
snoko,- <oblly .oBTE,- «SETS; <SEIN, <SETD, <SETO; «SEPS) 


@® Data file error (.OPEN, .OPENA, -OPENR, .DATA, «CLOSE, or 
~-READ between .ENABLE DATA and .DISABLE DATA) 


Note that the .ONERR directive applies only to the error 
conditions listed; errors returned from a task external to 
Indirect (for example, a DCL syntax error) are not processed by 
the .ONERR directive. 


Format 
-ONERR- label 

Upon detecting an error, the processor passes control to the line 
Starting with .label:. The .ONERR directive must be issued 
before Indirect encounters the error condition. If the directive 
is executed (one of the listed errors 1S encountered), error 
processing passes to the specified label. If the label specified 
by the .ONERR directive does not exist and an error condition has 


occurred, command processing terminates. 


Once an .ONERR condition has occurred, another .ONERR directive 
must be issued to trap a future error. 


Example 
-ONERR i100 
Upon detecting one of the error conditions, Indirect passes 


control to the line labeled .100:. 
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~OPEN - OPEN SECONDARY FILE 


4.35 .OPEN - OPEN SECONDARY FILE 


The .OPEN directive opens a specified secondary file as an output 
file. The .DATA directive is used to place data in this 
secondary file. 

Format (brackets not part of syntax) 


-OPEN [#n] filename 


where: 

filename A file to be opened as an output file. The 
default file type is .DAT. 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


Note that you cannot include a comment that begins with a 
semicolon (;comment) in an .OPEN statement. Doing so results in 
a syntax error. (Comments that begin with an exclamation mark 
('comment) are accepted.) 
Example 

-OPEN SECOUT 


This directive opens the file SECOUT.DAT as an output file. 
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~-OPENA - OPEN SECONDARY FILE FOR APPEND 
4.36 .OPENA - OPEN SECONDARY FILE FOR APPEND 
The .OPENA directive opens a secondary file and appends all 
subsequent data to the file. 
Format (brackets not part of syntax) 
-OPENA [#n] filename 


where: 


filename A secondary file to be opened with subsequent data 
appended to it. The default file type is .DAT. 


#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


Note that you cannot include a comment that begins with a 
semicolon (;comment) in an .OPENA statement. Doing so results in 
a syntax error. (Comments that begin with an exclamation mark 
(!comment) are accepted.) 


If the specified file does not already exist, .OPENA becomes’ the 
-OPEN directive by default. 


Example 
.OPENA SECOUT 


This directive opens the file SECOUT.DAT as an output file and 
appends subsequent data to it. 


-~OPENR - OPEN FILE FOR READING 


4.37 .OPENR - OPEN FILE FOR READING 


The .OPENR directive opens a file for reading with the .READ 
directive. 


Format (brackets not part of syntax) 
-OPENR [#n] filename 
where: 


filename A file to be opened for reading. The default file 
type is .DAT. 


#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


You cannot include a comment that begins with a_e semicolon 
(;comment) in an .OPENR statement; it results in a syntax error. 
(Comments beginning with an exclamation mark (!comment) are 
accepted. ) 
Examples 

-~OPENR INDADD 


This directive opens the file INDADD.DAT for reading with the 
-READ directive. 


~OPENR DATLIB.ULB/LB:DATINP 


This directive opens for reading the library module DATINP 
contained in the universal library DATLIB. 


-PARSE - PARSE STRINGS INTO SUBSTRINGS 


4.38 .PARSE - PARSE STRINGS INTO SUBSTRINGS 


The .PARSE directive parses strings in a command line into 
substrings. 


Format 
-PARSE <string> <control-string> <varl> <var2> ... <var9> 


The string is broken up into substrings as specified by the 
control string. The substrings are stored in the specified 
variables. The first character of the control string delimits 
the first substring, the second character of the control string 
delimits the second substring, and so on. The last character of 
the control string is repeated if the number of variables exceeds 
the length of the control string. If you specify more variables 
than substrings, the additional variables are set to null 
strings. If you specify fewer variables than the number of 
substrings that can be parsed, the last variable contains the 
unparsed fragment of <string>. 


The symbol <STRLEN> contains the actual number of substrings that 
Indirect processed (including explicit null substrings). 


Example 
.-PARSE COMMAN " ," FILE Ai A2 A3 A4 AS 


Given that COMMAN contains "TESTFILE IND,DCL,,LOA", this 
directive has the following results: 


FILE = TESTFILE 


Al = IND 
A2 = DCL 
A3 = null 
A4 = LOA 
A5 = null 


<STRLEN> contains a 5. 


.PAUSE - PAUSE FOR OPERATOR ACTION 
4.39 .PAUSE - PAUSE FOR OPERATOR ACTION 


.PAUSE is provided for compatibility with RSX Indirect. It is a 
no-op under the PRO/Tool Kit. 


»~-READ - READ NEXT RECORD 


4.40 .READ - READ NEXT RECORD 


The .READ directive reads the next record into a specified string 
variable. The entire record is written into the variable. If 
the record is longer than 132 (decimal) characters, an error 
occurs. 


After every .READ operation, the special symbol <FILERR> contains 
the FCS-11 file code for the read and the special symbol <EOF> 
reflects whether an end-of-file was’ found. (Note that .OPENR 
does not clear <EOF>.) If an error or end-of-file occurs, the 
string variable remains unchanged from its previous state. 


Format (brackets not part of syntax) 


.READ [#n] SSSSSS 


where: 

#n An optional file number that specifies the file 
from which the record is to be read. The file 
number must be one of the numbers used in a 
previous .OPENR' statement. The default is #0. 
You can substitute a numeric symbol for the value 
n by enclosing the symbol in apostrophes. 

SSSSSS The string variable into which the record will be 
read. 

Example 

-ENABLE SUBSTITUTION 
-~OPENR FILE 
IF <FILERR> NE 1 .GOTO ERROR 

. LOOP: 
»~READ RECORD 
~LFT <EOF> .GOTO DONE 
-IF <FILERR> NE 1 .GOTO ERROR 
; ‘RECORD’ 
.GOTO LOOP 

. ERROR: 

. DONE: .CLOSE 


»-READ - READ NEXT RECORD 


These directives open the file FILE.DAT for reading, read each 
record into the string variable RECORD, display each record on 
the terminal screen, and close the file. 


»~-RETURN - RETURN FROM A SUBROUTINE 


4.41 .RETURN - RETURN FROM A SUBROUTINE 


The .RETURN directive signifies the end of a subroutine = and 
returns control to the line immediately following the .GOSUB 
directive that initiated the subroutine. 

Format 


- RETURN 


~SETT/.SETF/.SETL - SET SYMBOL TO TRUE OR FALSE 


4.42 .SETT/.SETF/.SETL - SET SYMBOL TO TRUE OR FALSE 


The .SETT, .SETF, and .SETL directives define or change the value 
of a specified logical symbol. If the symbol has not been 
defined, Indirect makes an entry in the symbol table and sets the 
logical symbol to the value specified. If the symbol has already 
been defined, Indirect resets the symbol accordingly. Indirect 
exits with a fatal error if the logical symbol was defined 
previously as a numeric or string symbol. 


Formats 
-SETT SSSSSS 
-SETF SSSSSS 


-SETL ssssss Illllll 


where: 

SSSSSS The 1- to 6-character logical symbol to be 
assigned a true or false value. 

lililll A logical or numeric expression. SSSSSS is 
assigned the value of 111111 when the logical 
expression is evaluated. 

Examples 

-oOETT X 


This directive sets the logical symbol X to true. 
-SETF ABCDE 

This directive sets the logical symbol ABCDE to false. 
-SETL TEST SWITCHA! SWITCHB 


This directive sets the logical symbol TEST to true if SWITCHA or 
SWITCHB is true. 


~SETN - SET SYMBOL TO NUMERIC VALUE 


4.43 .SETN - SET SYMBOL TO NUMERIC VALUE 


The .SETN directive defines or changes the value of a _ specified 
numeric symbol. If the symbol has not been defined, Indirect 
makes an entry in the symbol table and sets the symbol to the 
numeric value specified. If the symbol has already been defined, 
Indirect resets the symbol accordingly. Indirect exits with a 
fatal error if the numeric symbol was previously defined as a 
logical or string symbol. 


Format 


-SETN SSSSSS numexp 


where: 
SSSSSS The 1- to 6-character numeric symbol. 
numexp A numeric expression. 


When specifying a numeric value to assign to a symbol, you may 
combine a numeric symbol or constant with another numeric symbol 
or constant to form a numeric expression. If numeric expressions 
are used, no embedded blanks or tabs are permitted. Evaluation 
is done from left to right unless parentheses are used to form 
Subexpressions that are evaluated first. The radix of an 
expression is octal if all the operands are octal and decimal 
mode has not been enabled; otherwise the radix is decimal. 


Examples 
.SETN NUMBER 27 


This directive assigns to the numeric symbol NUMBER the value 27 
(octal). 


-SETN Al 3*(A2-5) 


This directive assigns the numeric symbol Al the value of symbol 
A2 minus 5 multiplied by 3. 


~SETO/.SETD - SET SYMBOL TO OCTAL OR DECIMAL 


4.44 .SETO/.SETD - SET SYMBOL TO OCTAL OR DECIMAL 


The .SETO and .SETD directives redefine the radix of a specified 


numeric symbol (wi 


If the symbol has 
the symbol table 
a value of 0. If 
resets the symbol 
if the symbol was 
symbol. 


Formats 
-SETO sSSSSSS 


-SETD SSSSSS 


where: 
SSSSSS The 
ass 
Example 
-SETN A 10 
-OoOETD A 
-coETO A 


thout affecting the symbol’s actual value). 


not been defined, Indirect makes an entry in 
and sets the symbol to the specified radix with 
the symbol has already been defined, Indirect 
accordingly. Indirect exits with a fatal error 
previously defined as a logical or string 


1- to 6-character numeric symbol to be 
igned an octal or decimal radix. 


; Sets symbol A to 10 (octal) 

; Defines A as a decimal radix symbol with a 
value of 8 (decimal). 

; Defines A back to original radix with a 
value of 10 (octal). 


~SETS - SET SYMBOL TO STRING VALUE 


4.45 .SETS - SET SYMBOL TO STRING VALUE 


The .SETS directive defines or changes the string value of a 
Specified string symbol. If the symbol has not been defined, 
Indirect makes an entry in the symbol table and sets the symbol 
to the specified string value. If the symbol has been defined, 
Indirect resets the symbol accordingly. Indirect exits with a 
fatal error if the symbol was defined previously as a logical or 
numeric symbol. 


Format 


-SETS ssssss strexp 


where: 
SSSSSS The 1- to 6-character string symbol. 
strexp Any string expression. 


Indirect assigns to the specified symbol the string value 
represented by the string expression strexp. If a string 
constant is used in strexp, the constant must be enclosed by 
quotation marks ("constant"). 
You can combine a string symbol, constant, or substring with 
another string symbol or substring by the string concatenation 
operator (+) to form a string expression. 
Examples 

SETS A "ABCDEF" 


This directive assigns to the string symbol A the string value 
ABCDEF. 


-SETS STR2 "Z2ZZ" 
This directive assigns string symbol STR2 the value Z22Z. 
SETS X STR2+"ABC" 


This directive assigns string symbol X the value of symbol STR2 
plus ABC (that 1s ZZZABC). 


.SETS X STR2+A[1:3] 
This directive is equivalent to the previous directive; it 


assigns the string symbol xX the string value of STR2 plus the 
first three characters of string A (that 1S ZZZABC). 
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DEFINE 


Prompts 


Logical Name? logical_name 
Equivalence Name? equiv_name 


Qualifiers 
_/USER 


Places the logical name in the user logical name table. 
Logicals created in the user logical name table are deleted 
when you exit any application (including DCL). 


/SESSION 


Places the logical name in the session logical name table. 
Session logical names are deleted when you logout of the 
system. If you do not explicitly specify a logical name 
table, the default is /SESSION. 


/OYSTEM 


Places the logical name in the system logical name table. 
All system users can access the logical name. 


System logical names are never deleted unless an explicit 
deassign logical operation is performed. 


/FINAL 
Indicates that the equivalence name string should not be 
translated iteratively; logical name translation should 
terminate with the current equivalence string. The /FINAL 
qualifier is synonymous with: 
/TRANSLATION_ATTRIBUTES: TERMINAL 
/TRANSLATION_ATTRIBUTES: [(keyword[,...])] 
Specifies one or more attributes that modify a logical name 
string. The /TRANSLATION_ATTRIBUTES qualifer is positional 


and must be specified before the logical name is specified. 


You can specify the following keywords for translation 
attributes: 


DEFINE 


CONCEALED Indicates that the logical name is a concealed 
device name. If you specified the CONCEALED 
attribute, the logical name must be a device 
name of the form ddnnn: and the equivalence 
name must be of the form -—_ddnnn:[directory.]. 
The device name in the equivalence name must be 
present. The [directory.] portion Of the 
equivalence name is optional. 


TERMINAL Indicates that the equivalence name string 
should not be translated iteratively; logical 
name translation should terminate with the 
current equivalence string. 


If you specify only one keyword, you may omit the 
parentheses. Only the attributes you specify are set. 


Examples 
S$ DEFINE CHARLIE: DW001:[CHARLES] 


S PRINT CHARLIE:TEST.DAT 


The DEFINE command associates the logical name CHARLIE: 
with the directory name [CHARLES] on the device DWQO01. 
Subsequent references to the logical name CHARLIE: result 
in the correspondence between the logical name CHARLIE: and 
the disk and directory specified. The PRINT command queues 
a copy of the file DW001:[CHARLES]TEST.DAT to the default 


print queue. 


S$ DEFINE CHARLIE: DW001:[CHARLES] /USER 
The DEFINE command associates the logical name CHARLIE: 
with the directory name [CHARLES] on the device DW001: and 
makes the assignment in the user logical name table. 


$ DEFINE/TRANSLATION_ATTRIBUTES:CONCEALED PDOO1: - 
$-_DW002:[CHARLES. ] 


S DIRECTORY PDO001:[USERFILES ] 


Directory PD1:[USERFILES ] 
28-JUN-85 11:20 


TEST .DAT 4 27-JUN-85 17:21 
Total of 4./4. blocks in 1. files 
The DEFINE command associates the logical name PDOQOQ1: with 


the directory name [ CHARLES ] on the device DWOO02. 
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DEFINE 


Subsequent references to the device PDOO1: result in the 
device and directory specified as being used as the MFD for 
all file operations. 


S DEFINE/TRANSLATION_ATTRIBUTES: TERMINAL TEMP: XX001: 


The DEFINE command associates the logical name TEMP: with 
the device xXx001. Subsequent references to the logical 
TEMP: will result in the device XX001: being used without 
any further translation attempts on the equivalence name 
XXO001:. 


DELETE 


3.19 DELETE 


DELETE removes a file specification entry from a directory, 
releases the corresponding storage space occupied by those files, 
and causes any data in the corresponding file or files to be 
inaccessible. 


Syntax 

DELETE[/qualifier[s]] filespec[,s] 
qualifier 

Can be one or more of tics Panton ace 


/LOG 

/QUERY or /CONFIRM 

/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yyy 
/ TODAY 

/EXCLUDE: filespec 

/{NO]WARNINGS 


filespec 


Specifies the file or files to be deleted. You must specify 
the name, file type, and version number fields of the 
filespecs you want to delete. Device and directory fields 
default to your current device and directory. DELETE 
accepts wildcards in any field except the device field. You 
need not supply a efile type to delete a file with a null 


file type. 
Prompts 

Files(s)? Filespec[,s] 
Qualifiers 


/LOG 


Specifies that a list of the files deleted be displayed on 
your terminal. 


DELETE 


/QUERY or /CONFIRM 


Specifies that you want to decide which files should be 
deleted on an individual basis. Each file that is specified 
in the command is named. You may enter one of four 


characters: 


Y - Deletes file named and goes on to next file. 

N - Does not delete file named and goes on to next 
file. 

G - (Go) Deletes the file and goes on to delete all 
other files specified. 

Q - (Quit) Does not delete the file and exits the 
DELETE command. No more files are deleted. 

Remember that you can specify files by default or wildcard. 


If you do not specify a version 
default. 

/DATE:dd-mmm-yy 
The /DATE qualifier specifies that 


command 
for /DATE. 


/SINCE: dd-mmm-yy 


The /SINCE qualifier specifies that 


command to 
Specified by /SINCE. 


/ THROUGH: dd-mmm-yy 
The /THROUGH qualifier specifies that 
command to affect only files created 
specified by /THROUGH. 
/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers 
specify that you want the DELETE 
files created within that range. 
/TODAY 
The /TODAY qualifier specifies that 


command to affect only files created 
command is issued. 


3-53: 


number, /QUERY is the 


you want the DELETE 


to affect only files created by the value specified 


you want the DELETE 


affect only files created on or since the value 


you want the DELETE 
on or before the value 


can be combined to 
command to affect only 


you want the DELETE 
on the same day as the 


DELETE 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the DELETE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 


/{NO]WARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
specified do not exist. 


DELETE/DIRECTORY 


3.20 DELETE/DIRECTORY 


This command deletes an empty directory. An error message 
appears if you attempt to delete a directory that is not empty. 
Syntax 


DELETE/DIRECTORY [device: ][dirspec] 


device: 
Is an optional device name, such as DW1: or SY:. If you do 
not specify a device name, the system searches the current 
default device for the directory to delete. See the Tool 


Kit User’s Guide for further details on device names. 
dirspec 


Is a directory name enclosed in square brackets. An example 
is [USERFILES]. 


Prompts 


Directory? [device: ][dirspec] 
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3.21 DIBOL 


This command invokes the PRO/Tool Kit DIBOL compiler 
DIBOL source code files. 


NOTE 


Please refer to the language documentation 
additional information. 


Syntax 


DIBOL[/qualifier[{s]] filespec[,s][/qualifier[s]] 


qualifier 
Can be one or more of the following: 


/{NO]BUILD 

/(NO]CROSS_REFERENCE 

/ (NO ]DEBUG 

/(NO]LIST[:£1lespec] 
/{NOJOBJECT[:filespec] 

/{NO]JOPTIMIZE 

/PAGE_SIZE:number (D:system default) 
/{NO]STANDARD 

/(NO]SHOW 

/{(NO]WARNINGS 


filespec 
Is the name of a DIBOL source code file. 


NOTE 


to 


for 


If you want to reference a universal library 
containing source code modules, use the following 


format: 


compile 


DIBOL[/qualifiers[s] filespec[,s][/qualifier[s] libr_spec/LIBR 


libr_spec 


Is the name of the universal (default) library. 


DIBOL 


/LIBR 


Signals the DIBOL compiler that libr_spec is a universal 
(default) library. You may include only one such library in 
each compilation. 

Prompts 
File(s)? filespec[,s] 


Qualifiers 


/{NO]BUILD 


/BUILD causes the build option to be invoked automatically 
after the compilation phase. This qualifier creates .CMD 
and .ODL files for direct input to the Professional 
Application Builder (PAB). 


/[NO]CROSS_REFERENCE 


The /CROSS_REFERENCE qualifier causes the compiler to 
produce a list file and to add a cross reference table to 
the end of the listing file. 


/{NO]DEBUG 


/DEBUG includes extra information for the DIBOL debugger. 
The default is /NODEBUG which prevents the inclusion of this 
information. 

/{NO]LIST[(:filespec] 
/LIST causes the DIBOL to output a file with the same name 
as the source listing. /LIST creates this output. You may 
change the name of this output file by typing: 
gLIST new. fi lespec 
Refer to NOTE in /[NO]OBJECT. 

/{(NOJOBJECT[:filespec] 


/OBJECT creates an object module with the same name as_ the 


source listing and is the default value. fOBJECT: 
new_filespec creates an object file with a filename 
different than the source filename. /NOOBJECT suspends the 
creation of an object file. (When you list more than _ one 


source file on the command line and you specify /OBJECT, 
DIBOL creates an object file with the name of the first 
source file listed.) 


DIBOL 


NOTE 


Use of the qualifiers /NOOBJECT and /NOLIST allows 
the DIBOL command to check for errors. | 


/PAGE_SIZE:n 


The /PAGE_SIZE qualifier specifies the number of lines per 
page in the listing file. 


/OPTIMIZE 
/OPTIMIZE causes DIBOL to optimize the object file. The 
default is /NOOPTIMIZE which does not produce an optimized 
object file. 

/[NO]STANDARD 


/STANDARD flags all occurrences of P/OS (RSX-11M-PLUS) 
extensions to DIBOL-83. This is the default. 


/SHOW: (arg[,...]) 


Table 3-1 shows the value of arg. In the table, the letter 
"D" indicates the default argument for this qualifier. 


Table 3-1: Argument Values for /SHOW Qualifier 


Argument Default Description 

ALL Shows everything. 

NONE : Shows only source (nothing else). 

COND D Shows non-compiled conditionals. 
NOCOND Does not show non-compiled conditionals. 
INCLude D Shows included files. 

NOINCL Does not show included files. 

TABLes Shows symbol and label tables. 

NOTABL D Does not show symbol and label tables. 
SOURCe D Shows DIBOL source. 

NOSOUR Does not show DIBOL source. 


DIBOL 
/{(NO]WARNINGS 


/WARNINGS displays (or prints if accompanied by /LIST) 
warning messages 


produced by the DIBOL compiler; /WARNINGS 
is the default value. /NOWARNINGS suppresses the display 
(listing) of warning messages. 
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3.22 DIFFERENCES 


This command invokes the Compare (CMP) utility (refer to Chapter 
6), which compares two ASCII (text) files, line by line, to 
determine if parallel records (lines) are identical. After this 
comparison, DIFFERENCES produces a listing of any differences 
between the two files. 


Syntax 

DIFFERENCES[/qualifier[{s]] input_filel input_file2 
qualifier 

Can be one or more of the following: 


/CHANGE_BAR[:n] 

/IGNORE: (arg[,s]) 
BLANK_LINES 
COMMENTS 
FORM FEEDS 
SPACING 
TRAILING BLANKS 

/LINES:n 

/NONUMBERS 

/OUTPUT: filespec 

/SLP[:au] 


input. fiiel 


Specifies the first of two files to be compared. The 
filename must be included, and the default file type is 
.-MAC. 


input_file2 


Specifies the second of two files to be compared. The 
filename must be included, and the default file type is 
~-MAC. 

Prompts 


Filespeci? input. filet 
Filespec2? input_file2 


DIFFERENCES 


Qualifiers 
/CHANGE_BAR[ :nnn] 


Specifies that the output consists of a listing of infile2 
with change bars applied to each line in infile2 that does 
not have a corresponding line in infile1l. The nnn argument 
is the number of the ASCII character to be used for the 
change bar. The default is 041, the exclamation point (!). 
The following are codes for some commonly used ASCII 
characters: 


041 
043 
044 
052 
053 
074 
076 
077 
074 


— VVA + * UA = 


/IGNORE: (arg[,s]) 


BLANK_LINES 
COMMENTS 

FORM FEEDS 
SPACING 
TRAILING_BLANKS 


Specifies that you want certain defaults to be ignored in 
making the comparison. Without the /IGNORE qualifier, the 
comparison is strictly line-by-line. If you specify only 
one argument, you do not need the parentheses. If you 
Specify more than one argument, enclose them in parentheses 
and separate them with commas (,). 


The default is to include all these factors in the 
comparison. 


The BLANK_LINES argument specifies that blank lines are _ to 
be excluded from comparison. The default is to include 
blank lines in the comparison. 


The COMMENTS argument specifies that comments, that is, text 
preceded by a semicolon (;) not be included in the 
comparison. Otherwise, comments are compared like all other 
text. 


DIFFERENCES 


The FORM_FEEDS argument specifies that lines beginning with 
a single form feed character (CTRL/L) are to be excluded 
from the comparison. The default is to include such lines 
in the comparison. 


The SPACING argument specifies that any Sequence of blank 
and tab characters is to be interpreted as a single blank 
for the comparison. This argument is useful when comparing 
source files that differ only in their spacing. The output 
listing includes blanks and tabs as they are found in _ the 
input files, but the blanks and tabs are ignored. The 
default is to compare sequences of blanks and tabs like any 
other characters. 


The TRAILING BLANKS argument specifies that all blanks 
following the last nonblank character in the line be ignored 
in the comparison. The default is to compare trailing 
blanks like all other characters. If you specify both 
TRAILING_BLANKS and COMMENTS in your /IGNORE qualifier, any 
blanks preceding a semicolon (;) are also ignored. 


The DCL DIFFERENCES command does not have quite the same 
defaults as CMP, the File Compare Utility, which DIFFERENCES 
invokes. Specify / IGNORE: (BLANK_LINES, FORM_FEEDS ) to 
duplicate the CMP defaults for blank lines and form feeds. 
Other CMP defaults need not be specified. 


/LINES:n 
Specifies that n lines must be identical before a match is 
recognized. The default value for nis three identical 
lines. 


/{NO]NUMBERS 


/NONUMBERS specifies that lines in the output file not be 


preceded by line numbers. The standard output listing 
automatically includes line numbers. Line numbers” start 
with 1 in increments of one. All lines are numbered, 


including blanks. 
/OUTPUT: filespec 
Specifies that the output listing be written to the file 


named in the qualifier. Normally, this output appears on 
your terminal. 


DIFFERENCES 


/SLP[ :au] 


Specifies that the output listing take the form of an _  SLP 
indirect command file. When you include this qualifier, the 
output listing is an SLP indirect command file that makes. 


infilel identical to infile2. The optional au argument, 
preceded by a colon, is a 1- through 8-character 
alphanumeric audit trail symbol. For more information on 


the Source Language Input Program (SLP), see Chapter 11. 
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3.23 DIRECTORY 


DIRECTORY displays information for an individual file or a group 
of files. 


Syntax 
DIRECTORY[/format-qual][{/other-qual[s]] [filespec[,s]] 


format-qual 


Controls the appearance of the directory list and can be one 
of the following: 


/FULL 
/BRIEF 
/FREE[ddnnn: ] 
/ SUMMARY 
/ATTRIBUTES 


other-qual 


Modifies the list of files by creation date or exclusion and 
may be one or more of the following: 


/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 

/OUTPUT: 

/NOWARNINGS 


With PRO/DECnet DCL extensions, the following qualifier is also 
available: 


/WIDTH:n 


filespec[,s] 


Specifies the file or files for which information should be 
displayed. If you do not supply a filespec, the complete 
default directory is displayed. 


You can supply one or more filespecs, separated by commas, 
to display directory information on the files you name. 


DIRECTORY 


You can use wildcards in place of any filespec field except 
the device field. If you do not supply a version number, 
only information on the most recent versions is displayed. 
However, if you do not supply a file type, a null file type 
is assumed. If you do not know the file type, use a 
wildcard. 


You can display another directory by supplying the directory 
mame in this field. You can also specify device names in 
the form ddnnn: in this field. 


If you name files in two directories, you should name files 
for the default directory first. If you name files from 
another device or directory first, the defaults are 
canceled. 


Prompts 
None 
Qualifiers 
Qualifiers are in two groups: 


1. Format qualifiers control the appearance of the 
directory. 


2. Other qualifiers modify the list of files by creation 
date or exclusion. 


If you do not supply a qualifier from the format-qual list, 
the display is in standard format, which shows: the 
filename, type, and version number; the number of blocks the 
file occupies; and the date and time of creation. 


If you do not include any qualifier from the other-qual 
list, the display includes all files that otherwise qualify. 


Format Qualifiers 

/BRIEF 
Specifies that the display give filenames, types, and 
version numbers only. 

/FULL 
Specifies that the complete directory entry be displayed, 
including file ID number, blocks used and allocated, the 


owning UIC, protection status of the file, in addition to 
all the information in the standard display. 
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/ SUMMARY 


Specifies that the display give only the total number of 

blocks allocated and used for the specified files. If you 
give no filespecs in the command, the display shows’ the 
total blocks allocated and used for the default directory. 


/FREE [ddnnn: ] 


Specifies that the display give the free space and number of 
free file headers on the default device or a specified 
device. 


/ATTRIBUTES 


Displays the Record Management Services (RMS-11) attributes 
of a file or files. This display includes filename and 
type, creation date and time, file organization, protection 
status, allocation information, last access date and time, 
record format, record size, primary and alternate key 
definitions for indexed files, and bucket size for indexed 
and relative files. This qualifier invokes the RMS-11 DSP 
utility. 


NOTE 


This display is produced for any file you specify in 
a DIRECTORY command, whether or not the file is an 
RMS-11 file. 


Some display information may not be meaningful for non-RMS 
files. 


Other Qualifiers 
/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the DIRECTORY 
command to affect only files created by the value specified 
for /DATE. 


/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the DIRECTORY 
command to affect only files created on or since the value 
specified by /SINCE. 


DIRECTORY 


/ THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the DIRECTORY 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
Specify that you want the DIRECTORY command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the DIRECTORY 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the DIRECTORY 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "x" 
wildcard. 


/OUTPUT: filespec 


The OUTPUT qualifier specifies that the output of the 
DIRECTORY command be placed in a file having the file 
specification you supply. 


/{NO]WARNINGS 
The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
specified do not exist. 

Additional Qualifiers Available with PRO/DECnet 

Command Qualifiers 

/WIDTH:n 
The /WIDTH qualifier specifies the width of the display for 
the default and /FULL format displays only. The default 
value is 72. At least one field is always displayed per 


line, even if that field exceeds the maximum width 
specified. 
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3.24 DISMOUNT 


This command marks the volume mounted on the specified device to 
be logically off-line and disconnected from the file system. 


Syntax 
DISMOUNT device: [volumelabel ] 

device: 
Is the name of the device on which the magnetic medium 
containing the volume is currently mounted. This argument 


can be in the form ddnnn:, or it can be a logical name 
previously assigned to the device by the MOUNT command. 


volumelabel 


Is the name of the volume. If the volume currently mounted 
in device does not match the volume label you specify, the 
system does not dismount the device. 


Prompt 


Device? device: [volumelabel] 


DUMP 


3.25 DUMP 


DUMP displays or prints the contents of a file or volume in 
ASCII, hexadecimal, octal, or decimal format. This command 
invokes the File Dump (DMP) Utility. (Refer to Chapter 7.) 


Syntax 

DUMP[/qualifier[s]] filespec 
qualifier 

Can be one or more of the following: 


/ASCII 

/BASE_ADDRESS:n:m 
/BLOCKS:n:m 

/BYTE 

/DECIMAL 

/FILE: file-number:sequence-number 
/FILE_HEADER[:[NO]FORMATTED] 
/HEADER 

/HEXADECIMAL 

/ IDENTIFICATION 

/LOGICAL_ BLOCK 

/ LONGWORD 

/ LOWERCASE 

/NUMBER[ :n] 

/OCTAL 

/OUTPUT: file-name 

/RADIX_50 

/ RECORD 

/WORD 


filespec 
Is the file specification to be displayed (dumped). 
Prompts 
File? filespec 
Qualifiers 
/ASCII 
/ASCII specifies that the data should be dumped one byte at 
a time in ASCII mode. This qualifier displays the full DEC 


Multinational Character Set. The control characters (0-37) 
(octal) are printed as a circumflex (*), followed by the 
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alphabetic character corresponding to the character code 
plus 100. For example, bell (code 7) is printed as *G (code 
107). The control characters from 200 (octal) through 240 
(octal) are displayed as Chr, where Chr is the control 
character + 100 (octal). 


Lowercase characters (140-177) (octal) are printed as a 
percent sign (%), followed by the corresponding uppercase 
character (character code minus 40), unless the /LOWERCASE 
qualifier 1S specified. The /ASCII and /OCTAL qualifiers 
are mutually exclusive when dumping bytes. 


/BASE_ADDRESS:n:m 


This qualifier specifies a two-word base block address (the 
initial base address is 0,0), where n is the high-order base 
block address (octal), and mis the low-order base block 
address (octal). The address may also be specified in 
decimal by using a period after the number. All future 
block numbers specified by the /BLOCKS qualifier will be 
added to this value to obtain an effective block number. 
This qualifier is useful for specifying block numbers that 
exceed 16 bits. For example: 


/BASE_ADDRESS:1:0 


specifies that all future block numbers will be relative to 
65536 (decimal) (200000 octal). Also, the following clears 
the base address: 


/BASE_ADDRESS:0:0 


When the /BASE_ADDRESS appears in a command line, no blocks 
are dumped. The only result of the command line is to set 
the base address. 


NOTE 


The following pertains if you run DUMP directly as a 
Weir ity. 


Once this qualifier is specified, it remains in effect until 
Lc 1s used again to set a new base address. The 
/BASE_ADDRESS qualifier would be the /BA:n:m qualifier 
(refer to Chapter 7 for further information). 
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/BLOCKS:n:m 


Specifies the range of blocks to be dumped, where n is’ the 
first block and m is the last block. The values of n and m 
must not exceed 16 bits. In file mode only, the /BLOCKS:n:m 
qualifier is not required. If the /BLOCKS:n:m qualifier is 
not specified, DMP will dump all blocks of the specified 
file, relative to the current base address. 


If /BLOCKS:n:m is specified in file mode, it specifies the 
range of virtual blocks to be dumped. If /BLOCKS:n:m is 
specified as /BLOCKS:0 in file.mode, no virtual blocks are 
dumped. This is useful for dumping only the header portion 
of the file (see /HEADER). The /BLOCKS:n:m qualifier and 
the /RECORD qualifier are mutually excluSive. 


The /BLOCKS:n:m qualifier is a required parameter in device 
mode. When used in device mode, it specifies the range of 
logical blocks to be dumped. 


The value n represents the block number of the first block 
dumped. Successive blocks are labeled with a block number 
one higher than the preceding block number. The dump will 
continue until the block labeled m is dumped. 


/BYTE 

Specifies that the data be dumped in octal byte format. 
/DECIMAL 

Specifies that the data be dumped in decimal word format. 
/FILE: file-number:sequence-number 


In file mode, the file number can be used instead of a 
filename as a file specification for input. 


/FILE_HEADER[ : [NO] FORMATTED ] 


This qualifier is an optional parameter used in file mode. 
In addition, this qualifier has two options. FORMATTED, the 
default, causes a FILES-11 formatted dump of the header. 
NOFORMATTED specifies an unformatted octal dump. An octal 
dump occurs when DUMP is used on non-FILES-11 headers. goa 
specified, the /HEADER[:[NO]FORMATTED] qualifier causes the 
file header as well as the specified or implied portion of 
the file to be dumped. 
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/HEADER 
Specifies the format for data blocks that have the FILES-11 
header structure. Other blocks are output as an unformatted 
octal dump. 

/HEXADECIMAL 


Specifies that the data be dumped in hexadecimal byte 


format. Note that a hexadecimal dump reads from right to 
left. (See also the /LONGWORD and /WORD qualifiers.) 
/IDENTIFICATION 


Causes DMP’s version to be identified. This qualifier may 
be specified on a command line by itself at any time. 


/LOGICAL_BLOCK 


Requests logical block information for a file. The starting 
block number and a contiguous or noncontiguous indication 
for the file are displayed. 


/ LONGWORD 


Specifies that the data be dumped in hexadecimal double-word 
format. 


/ LOWERCASE 


Specifies that the data should be dumped in lowercase 
characters. 


/NUMBER[ :n] 


Specifies a memory dump and allows control of line numbers. 
Line numbers are normally reset to zero whenever a block 
boundary is crossed. The /NUMBER[:n] qualifier allows lines 
to be numbered sequentially for the full extent of the file, 
that is, the line numbers are not reset when block 
boundaries are crossed. The optional value (:n) specifies 
the value of the first line number. The default is 0. The 
/NUMBER[ :n] qualifier is used with the output file 
Specification. 
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/OCTAL 


Specifies that the data should be dumped in octal format in 
addition to other formats specified. If no format 
qualifiers are specified, the default is octal. The /ASCII 
qualifier and the /OCTAL qualifier are mutually exclusive 
when dumping bytes. 


/RADIX_50 


Specifies that data be dumped in Radix-50 format words. 


/ RECORD 


Specifies that data be dumped a record at a time (rather 
than a block at a time). The data format is determined by 
setting any of these format qualifiers: /ASCII, /DECIMAL, 
/HEXADECIMAL, /LONGWORD, /RADIX50, or /WORD. 


The largest record that DUMP can process is 512 (decimal) 
bytes. 


The /RECORD qualifier and the /BLOCK qualifier are mutually 
exclusive. 


/WORD 


Specifies that the data be dumped in hexadecimal word 
format. 
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3.26 EDIT OR EDIT/EDT 


EDIT starts an interactive editing session with the EDT editor to 
create or modify a file. 


Syntax 
EDIT[/qualifier[s]] filespec 
qualifier 
Can be one or more of the following: 
/(NO]COMMAND[:filespec] 
/{NO]JOURNAL[ : filespec] 
/(NOJOUTPUT([:filespec] 


/{NO]RECOVER 
/{NO]READ_ONLY 


filespec 


Is the name of an existing file or the name of a file to be 
created. You must specify a filename, but the file type may 
be null. For example, the command: 


EDIT filename 
causes EDT to edit filename. ; 
Prompts 
File? filespec 
Qualifiers 
/{NO]COMMAND[ :filespec] 
Controls whether an EDT initialization file is read by EDT 
before editing begins. These files contain commands that 


alter the default setup for EDT, such as custom line-mode 
commands and change-mode key definitions. 


The default is /COMMAND:LB:[1,2]EDTSYS.EDT. If you use this 
qualifier and EDTINI.EDT or some other file you name does 
not exist, EDT issues no error message and continues with 
the editing session. 


If you do not want to use LB:[{1,2]EDTSYS.EDT, use the 
/NOCOMMAND qualifier. 
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/([NO]JOURNAL[:filespec] 


Controls whether EDT creates a journal file for the editing 
session. The default is to create a journal file with a 
filename the same as that of the input file with the type 
.JOU. You can specify a different name by including a 
fFilespec. 


The journal file consists of all editing commands and text 
entered during the session. If the editing session ends 
abnormally, such as through a system crash, or your 
inadvertently typing three CTRL/ZsS in succession, the 
journal file is saved. In such a case, you invoke EDT 
again, with the same command line as before plus the 
/RECOVER qualifier. Your editing session is repeated and 
all your editing is restored. If the editing session ends 
normally, the journal file is deleted. 


If you specify /NOJOURNAL, no journal file is created and no 
recovery is possible. 


/{(NOJOUTPUT[:filespec] 


If you do not specify this qualifier, the default is to 
create a file of the same name and type as the input file 
with a version number one higher than the input file. LT 
the file is new, EDT creates version number 1. You can 
alter the name of the output file by including a filespec 
with the /OUTPUT qualifier. Otherwise, the qualifier need 
not be included. 


If you specify /NOOUTPUT, you cannot exit EDT without 
including a filespec in your EDT EXIT command. 


/{NO]READ_ONLY 


Specifies whether you want simply to read the file or to 
edit it. If your command line includes /READ_ONLY, you can 
use ‘the £011] facilities. of EDT, but. you cannot exit. without 
including a filespec in your EDT EXIT command. Normally, 
you would use the EDT QUIT command if you had _ specified 


/READ_ONLY. The /READ_ONLY qualifier is equivalent to a 
combination of  /NOOUTPUT and /NOJOURNAL. You can use 
/READ_ONLY to look at files to which you have no write 
access. 


The default is /NOREAD_ONLY, which need never be specified. 
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/{NO]RECOVER 


Specifies whether EDT reads commands from a journal file 
prior to starting the editing session. With a journal file, 
your editing session can be restored if interrupted by a 
system crash or other problem. 


The default is /NORECOVER, which need never be specified. 


The /RECOVER qualifier requests EDT to open the input file 
and then read EDT commands and text from the file with the 
same filename as the input file and the file type .JOU. The 
command line with /RECOVER added to it must be identical to 
the command line that initiated the original failed editing 


session. This means that if you specified an EDT 
initialization file, you must specify the same file in the 
/RECOVER command line. If you specified a name for the 


journal file other than infile.JOU, you must include _ the 
/JOURNAL qualifier with the appropriate filespec. 


If journaling was not enabled on the original command line, 
you cannot recover the editing session. 


EDIT/PROSE 


3.27 EDIT/PROSE 


EDIT/PROSE invokes the PROSE editor from DCL. 
NOTE 
This section only describes the DCL command that 


accesses the PROSE editor. For further 


information on PROSE you should turn to the Prose 
User’s Guide. 


Syntax 


EDIT/PROSE/qualifier filespec 
qualifier 
/OUTPUT: filespec 


filespec 


Is the name of an existing input file that PROSE will 


or a new file spec that PROSE will first create and then 


edit. 


NOTE 
Whenever you leave a PROSE editing session, you 
cannot discard your edits from that session. If 


you do not want the output file, you have to 
delete it after exiting the editing session. 


Prompts 
File? filespec 
Qualifier 


/OUTPUT: filespec 


Causes EDIT/PROSE to name the output file with a different 
filename from the input filename. If you do not specify 


this qualifier, EDIT/PROSE creates a file of the same 


and type as the input file, but with a version number that 


is one higher than the input file. If the file is 
EDIT/PROSE creates version number 1. 


3.28 


This 
which 
files 


EDLI/ OUP 


EDIT/SLP 


command invokes the Source Language Input Program (SLP), 
is an editor designed for maintaining and updating source 
. (Reter to Chapter 11.) 


Syntax 


quali 


EDIT/SLP[/qualifier[{s]] filespec 
fier 
Can be one or more of the following: 


/{NO]AUDIT[ :arg] 
POSITION:n 
SiZe tn 
/{NO]CHECKSUM[:arg] 
/(NO]LIST{: filespec] 
/{NOJ]OUTPUT[:filespec] 
/{NO]REPORT 
/(NO]TAB 
/(NO]TRUNCATE[ :n] 


filespec 


Is the name of the source program to be updated by SLP. 


Prompts 


File? filespec 


Qualifiers 


/{NO] 


AUDIT[:(arg[s])] 
POSITION:n 
SIZE:n 


Controls whether the output file includes an audit trail, 
and optionally allows you to specify the location and size 
of the audit trail. You can specify one or both of these 
values. If you specify only one, you can omit the 
parentheses, but the parentheses are required syntax if you 
specify both POSITION and SIZE. Separate the two arguments 
within the parentheses by a comma (,). 


The POSITION: argument sets the starting position of the 
audit trail. The value of n can be from 0 through 132, 
representing the column at which the first character in the 
audit trail is to appear. This value is rounded up to the 


3-78 


EDIT/SLP 


next highest tab stop. The default is to start the audit 
trail at column 8:0. Note that this default causes audit 
trails of more than a single character to wrap around when 
displayed on standard video terminals. 


The SIZE: argument sets the length of the audit trail. The 

value of n can be from 0 through 14. The default is an 

audit trail of 8 characters. The audit trail itself is 

defined from within SLP. See Chapter 11. 
/{NO]CHECKSUM[:arg] 


Controls whether a checksum is calculated for the  SLP 


commands. If you specify checksum without an argument, SLP 
calculates the checksum value and prints it on your 
terminal. If you specify an argument, SLP calculates the 


checksum and compares it to what you have specified. If the 
numbers differ, a warning message is displayed, but the 
execution of SLP is not interrupted. 


The default is /NOCHECKSUM. 
/(NO]LIST[:filespec] 


The /LIST qualifier creates a listing of a file with line 
numbers. If you do not give a filespec, the default 
filespec is filename.LST. 


The default is /LIST. /NOLIST suppresses creation of the 
listing file. 


/{(NOJ]JOUTPUT[:filespec] 


Use this qualifier to change the name of the output file. 
The default output filespec is the same name and type as the 
input file and a version number one higher than the highest 
existing version of the file. If. you do -not. want: to 
override this default, you do not need this qualifier. 


The /NOOUTPUT qualifier suppresses creation of an output 
file. 


/[NO]REPORT 


Controls whether line truncations that result from audit 
trails are reported. If you specify /REPORT, you receive 
warning messages on your terminal and the affected lines are 
marked with a question mark (?) in place of the period (.) 
in the line number in the listing file. 


EDIT/SLP 


The default is /NOREPORT. 


/(NO]TAB 
Controls whether SLP replaces tabs or spaces at the end of 
each record containing an audit trail. If you specify /TAB, 
tabs are inserted. If you specify /NOTAB, spaces are 


inserted. The default is /NOTAB. 
/{NO]TRUNCATE[:arg] 


The TRUNCATE qualifier requests SLP to truncate each’ record 
in the input file when it creates the output file. This 
qualifier allows you to delete an audit trail from ae file 
previously updated with SLP. If you specify /TRUNCATE 
without a number, SLP truncates input records at the 
beginning position of the audit trail. If you specify a 
number, SLP truncates the records beginning at the column. 
The value of n can be from 0 through 132. 


The default is /NOTRUNCATE. 


EXIT 

3.29 EXIT 
Invoking this command, or pressing the EXIT key, causes you to 
exit PRO/Tool Kit. 
You Should not exit PRO/Tool Kit if any tasks are still active. 
This includes active tasks submitted to background mode by the 
SPAWN command. (Refer to Section 2.4.) You should either allow 
all tasks to finish, or you should abort them. 
Syntax 

EXIT 


Prompts 


None 


FIX 


3.30 FIX 


This command loads and locks a task into its partition. 
Subsequent requests for running the task are serviced more 
quickly because the task is memory-resident and does not have to 
be loaded from the disk before it can run. 

Fixed tasks remain physically in memory even after they exit. 
Therefore, they do not have to be reloaded when a request is made 
to run them. (Note that reexecuting fixed tasks is not always 
practical; to reexecute, the task must initialize all impure data 
and LUN assignments at run time.) Only a REMOVE command can _ free 
the occupied memory partition. 


Note the following requirements: 
e You must install a task before you fix it. 
® You cannot fix a task whose name is in the form ...xxx or 
XXX9S$. This is because the copy of the task with that form 
of name is a nonexecutable, prototype task. 
@® You cannot fix an active task. 
@ You should not fix a checkpointable task because doing. so 
makes the task noncheckpointable. 
See also the INSTALL command with the /FIX qualifier. 
Syntax 
FIX taskname [/qualifier] 
taskname 
Is the task or region to fix in memory. 
qualifier 


/REGION 
/READONLY_SEGMENT 


Prompt 


Taskname? taskname 


FIX 


Qualifiers 
/REGION 


Indicates that the task to be fixed is a region, such as a 
read-write common. 


/ READONLY_SEGMENT 


Fixes only the read-only segment of a multiuser task. 
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3.31 FORMAT 


This command deletes all existing files and sets up a hard disk 
so that that it is recognizable as a FILES-11 volume by its 
controller. Once you have formatted a disk, you can then use the 
INITIALIZE command to initialize it. 


Normally, the P/OS installation procedure formats the system 
disk. However, to connect additional hard disks to a 


Professional you must format each one by invoking the FORMAT 
command. 


Syntax 
FORMAT[/qualifier] device: 
qualifier 
/([NO]CONFIRM 
device: 
Is the name of the device on which the magnetic medium 
containing the volume is currently mounted. This argument 


can be in the form ddnnn[:], or it can be a logical name 
created with the ASSIGN or DEFINE command. 


Prompt 
Device? device: 

Qualifier 

/[NO]CONFIRM 
The /NOCONFIRM qualifier specifies that P/OS should not 
verify that the volume is already in FILES-11 format. The 
/CONFIRM qualifier asks you to verify the format request if 


the volume is already in FILES-11 format. The /CONFIRM 
qualifier is the default. 


FORTRAN 


3.32 FORTRAN 


FORTRAN invokes the PRO/Tool Kit FORTRAN-77 compiler 
FORTRAN language source files. 


NOTE 


Please refer to the language documentation 
additional information. 


Syntax 

FORTRAN([(/qualifier[s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/{(NO]CHECK 
/CONTINUATIONS:n 
/{NO]DEBUG 
/[NO]DLINES 

/ IDENTIFICATION 
/(NO]14 
/{(NO]LIST([:filespec] 
/ (NO ]MACHINE_CODE 


/(NO]MAP 
/(NOJOBJECT([:filespec] 
/{(NO]OPTIMIZE 
/({NO]SHAREABLE 
/ SOURCE 
/({NO]STANDARD: arg 
ALL 
NONE 
SOURCE 
SYNTAX 
/(NO]TRACEBACK: arg 
ALL 
BLOCKS 
LINES 
NAMES 
NONE 


/WORK_FILES:n 
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FORTRAN 


Filespec 
Is the name of the FORTRAN source file. 
Prompts 
File(s)? filespec[,s] 
Qualifiers 
/(NO]CHECK 


The /CHECK qualifier specifies that you want the compiler to 
check that all array references are within bounds. 


The default is /NOCHECK. 
/CONTINUATIONS:n 


The /CONTINUATIONS qualifier specifies the maximum number of 
continuation lines permitted in the code. The value of n 
can be from 0 through 99. The default is 5. 


/{NO]DEBUG 


Specifies that the compiler is to provide symbol table 
information for use by the PRO/TOOL KIT FORTRAN-77 symbolic 
debugger. When you use the /DEBUG command qualifier, you 
Should also use the /NOOPTIMIZE command qualifier. /NODEBUG 
is the default. 


/{[NO]DLINES 


The /DLINES qualifier specifies that lines with a "D" 
character in column 1 are to be compiled. The default is 
/NODLINES, meaning these lines are treated as comment lines. 
Use this feature for debugging. 


/IDENTIFICATION 


The /IDENTIFICATION qualifier causes the compiler to print 
its identification and version number on your terminal. 


/{NO]1I4 


The /I14 qualifier causes a two-word default allocation for 
integer variables. The default is /NOI4, meaning the 
compiler causes a single-word allocation for any integer 
variables not given an explicit length specification. 


FORTRAN 


/(NO]LIST[:filespec] 


Specifies whether a compiler listing should be generated. 
The default is /NOLIST, meaning no compiler listing is 
generated. 


If you do not supply a file specification for this 
qualifier, the listing has a filename derived from the name 
of the first source file in the FORTRAN command with the 
File type .LST. If you want the listing to have a different 
name, supply the name as an argument to the /LIST qualifier. 
If you do supply a name, the listing file appears in your 
directory but is not printed on the printer. 


The /LIST qualifier behaves in a different manner depending 
on whether it is given as a command qualifier or a filespec 
qualifier. If /LIST:LP: is used as a command qualifier, 
the listing file is placed in your directory and printed on 
the printer. If /LIST is used as a filespec qualifier, the 
listing file appears in your directory but is not printed on 
the printer. If /LIST is used as a filespec qualifier, the 
listing file takes the name of that file. 


NOTE 
The /MACHINE_CODE, /MAP, and /SOURCE, qualifiers 


all affect the contents of the compiler listing 
file. 


/{NO]MACHINE_CODE 


The /MACHINE_CODE qualifier specifies that you want the 
compiler listing to include binary machine code _ and 
diagnostics. The default 1s /NOMACHINE_CODE. 


/MACHINE_CODE implies /LIST. You do not need to include the 
/LIST qualifier unless you want to use it to establish a 
name for the listing file different from any of the 
filenames included in the compilation. 


The /MACHINE_CODE qualifier behaves in a different manner 
depending on whether it is given as a command qualifier or a 
filespec qualifier. If /MACHINE_CODE is used aS a command 
qualifier, the listing file is placed in your directory and 


printed on the printer. If /MACHINE_CODE is used as a 
filespec qualifier, the listing file appears in your 
directory but is not printed on the printer. If 


/MACHINE_ CODE is used as a filespec qualifier, the listing 
file takes the name of that file. 


FORTRAN 


/{NO]MAP 


The /MAP qualifier specifies that you want the compiler 
listing to include a storage map and diagnostics. 


/MAP implies /LIST. You do not need to include the /LIST 
qualifier unless you want to use it to establish a name for 
the listing file different from any of the filenames 
included in the compilation. 


The /MAP qualifier behaves in a different manner depending 
on whether it is given as a command qualifier or a filespec 
qualifier. If /MAP is used as a command qualifier, the 
listing file is placed in your directory and printed on the 
printer. If /MAP is used as a filespec qualifier, the 
listing file appears in your directory but is not printed on 
the printer. If /MAP is used as a filespec qualifier, the 
listing file takes the name of that file. 


/{(NOJOBJECT[:filespec] 


Determines whether or not an object module is generated by 
the compiler. The default is /OBJECT, which does create a 
module. The default name of the object file created by 
FORTRAN is the last-named source file with the file type 
-OBJ. If you want the object file to have a different name, 
supply the name as an argument to the /OBJECT qualifier. 


/NOOBJECT specifies that no object module is created. You 
can use the /NOOBJECT qualifier to get a compiler listing 
file to check for errors without generating object code. 


/{NOJ]OPTIMIZE 


Controls whether the compiler optimizes the compiled program 
to generate more efficient code. 


Use /NOOPTIMIZE in conjunction with the /DEBUG qualifier to 
link a  P/OS FORTRAN-77 program with the debugger so that 
variables always contain their updated values. 


/{NO]SHAREABLE 


The /SHAREABLE qualifier states that you want the compiler 
to generate pure code and pure data sections as read-only. 
This takes advantage of code sharing in multiuser tasks_~ on 
P7/OS:; 


FORTRAN 


/ SOURCE 


The /SOURCE qualifier specifies that you want the compiler 
listing to include the source code. 


/SOURCE implies /LIST. You do not need to include the /LIST 
qualifier unless you want to use it to establish a name for 
the listing file different from any of the filenames 
included in the compilation. 


The /SOURCE qualifier behaves in a different manner 
depending on whether it is given as a command qualifier ora 
Filespec qualifier. If /SOURCE is used aS a command 
qualifier, the listing file is placed in your directory and 
printed on the printer. If /SOURCE is used as a filespec 
qualifier, the listing file appears in your directory but is 


not printed on the printer. If /SOURCE is used as a 
filespec qualifier, the listing file takes the name of that 
file. 
/{NO]STANDARD:arg 

ALL 

NONE 

SOURCE 

SYNTAX 


The /STANDARD qualifier directs the compiler to look in your 
source code for extensions to ANSI standard (X3.9-1978) 
FORTRAN at the full-language level. If the compiler finds 
extensions, ie flags them and produces informational 
diagnostics. 


The ALL argument produces informational diagnostics for all 
detected extensions. 


The NONE argument produces no informational diagnostics. 


The SOURCE argument produces informational diagnostics for 
lowercase letters and tab characters in the source code. 


The SYNTAX argument is the same as /STANDARD with no 
argument. 


The default is /NOSTANDARD. 


/{NO]TRACEBACK: arg 
ALL 
BLOCKS 
LINES 
NAMES 
NONE 


FORTRAN 


/TRACEBACK controls the amount of extra code included in the 
compiled output for use by the OTS during error traceback. 
This code is used in producing diagnostic information and in 
identifying which statement in the FORTRAN source program 
caused an error condition to be detected during execution. 


The ALL argument states that error traceback information is 
to be compiled for all source statements, and function and 
Subroutine entries. 


The LINES argument is the same as ALL. 


The BLOCKS argument states that traceback information is to 
be compiled for subroutine and function entries and initial 
statements in sequences called blocks. This is the default. 


The NAMES argument states that traceback information is _ to 
be compiled only for subroutine and function entries. 


The NONE argument states that no traceback information is to 
be produced. 


/WORK_FILES:n 


The /WORK_FILES qualifier specifies the number of temporary 
on-disk files you want used during the compilation. The 
argument n can range from 0 through 3; the default is 2. 
Increasing the number of work files increases the maximum 
possible size of your program but decreases the speed of 
compilation. 


HELP 


3.33 HELP 


HELP displays information about the commands and utilities. 
Syntax 

HELP[/qualifier] [topic]... 
qualifier 

Can be one or more of the following: 

/OUTPUT: filespec 

/FILE: filespec 

/filename 

/ LOCAL 


ODL Ce a's 


Are up to four optional topics, separated by spaces, for 
which you want help. 


Prompts 

None 
Qualifiers 
/OUTPUT: filespec 


Permits you to name an output file where the requested help 
text is to be saved. The default is /OUTPUT:TI:. 


/FILE: filespec 
Specifies any file where help text is located. If you do 
not give a complete file specification, the defaults are 
LB:{1,2])filename.HLP. 


/filename 


Specifies that the help text begins with 
LB:{1,2]filename.HLP. 


/ LOCAL 


Specifies that the help text is in the file HELP.HLP in the 
default directory on the default device. 


INITIALIZE 


3.34 INITIALIZE 


This command deletes all existing files on a volume and imparts 
the standard FILES-11 file structure. INITIALIZE can also 
optionally check for bad blocks. Note that the volume must _ be 
formatted (see the FORMAT command) prior to being initialized. 


Syntax 


INITIALIZE[/qualifier[s]] device: volumelabel 
qualifiers 


/{NO]BAD_BLOCKS 
/CHECKPOINT_SPACE:n 
/{NO]CONFIRM 


device 


Is the name of the device on which the magnetic medium 
containing the volume is currently mounted. This argument 
can be in the form ddnnn[:], or it can be a logical name 
previously assigned to the device. 


volumelabel 


is the label that names the volume after initialization. It 
can be from 1 to 12 characters long. 


Prompts 


Device? device 
Volume name? volumelabel 


Qualifiers 

/{NO]BAD_BLOCKS 
/BAD_BLOCKS, the default, performs a check for bad blocks on 
the volume you are initializing. If any bad blocks are 
found, P/OS will not use them for storing information. LE 


you specify /NOBAD_BLOCKS, P/OS does not search for bad 
blocks on the volume. 


/CHECKPOINT_SPACE:n 


Allows you to control the size of a system checkpoint file 
on the volume being initialized. 


INITIALIZE 


/{NO]CONFIRM 


The /NOCONFIRM qualifier specifies that P/OS should not 
verify that the volume is already in FILES-11 format. The 
/CONFIRM qualifier asks you to verify the initialization 
request if the volume is already in FILES-11 format. The 
/CONFIRM qualifier is the default. 


INSTALL 
3.35 INSTALL 


INSTALL includes a specific task in the System Task Directory, 
thus making it known to the system. 


An installed task is dormant until it is requested to run by the 
Executive. You can request an installed task to run through the 
RUN command or through a variety of Executive directives under 
program Control. Examples of such directives are: RQSTS 
(Request), RUNS (Run), and SPWNS (Spawn). See the P/OS System 
Reference Manual for details on the directives. 


Syntax 

INSTALL[ /qualifier[s]] [$]filespec 
qualifier 

Can be one or more of the following: 


JEIX 

/NOREMOVE 
/READONLY_COMMON 
/TASK_NAME:taskname 
/[NO]WRITEBACK 


[S]filespec 


Specifies the name of the task image file containing the 
task you want to install. The default file type is .TSK. 
The dollar sign ($), if present, directs the system to 
search for the file in APPLSDIR. If you do not include the 
/TASK_NAME qualifier, the system installs the task under a 
name based on the first six characters of the filename 
unless another name was assigned through the TASK= option of 
the Task Builder. 


Prompts 
File? filespec 

Qualifiers 

/FIX 
Loads and locks a task into memory after installing it. 
P/OS can service requests for a fixed task much more quickly 


because it is memory-resident and does not have to be loaded 
from disk. 


INSTALL 


You can use the FIX command to fix a task that is already 
installed. See Section 3.30. 


/NOREMOVE 


When the DCL application exits, P/OS will not remove tasks 
or regions that have been installed with the /NOREMOVE 
qualifier. 


/READONLY_COMMON 


Specifies that a common or region is to be installed as 
read-only. 


/TASK_NAME:taskname 


Specifies the name by which the task is to be referenced. 
The default is set at link time. This qualifier overrides 
the link-time specification. 


/{NO]WRITEBACK 


Applies only when you install a read-write common. This 
qualifier controls whether or not the system writes the 
common back to its task image either when you remove the 
common from memory or when the system checkpoints the 
common. 


If you use /WRITEBACK, then any changes made to the common 
while installed are copied to the common’s task image when 
the common is checkpointed or you remove it. 


If you specify /NOWRITEBACK, then changes made to the common 


are not copied back to the image. The default (that is, 1f 
you do not specify either), is /NOWRITEBACK. 
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3.36 LIBRARY 


LIBRARY creates and maintains user-written library files, or 


libraries. Libraries can contain macro definitions, object 
modules, or, in the case of universal libraries, anything. 
LIBRARY invokes’ the Librarian Utility program (LBR). (Refer to 
Chapter 8.) 

Syntax 


LIBRARY[/operation][/qualifier[s]] libr_spec input_file 
operation 


Represents a specific subcommand form of LIBRARY (refer to 
each separately listed LIBRARY command). 


qualifier 
Refer to each separately listed LIBRARY command. 
libr_spec 


Specifies the name of the library. The default type is 
.OLB, specifying an object module library. 


input_file 


Specifies input files used as input for a new library file 
created with the /CREATE qualifier. 


Prompts 


Operation? operation 


LIBRARY/COMPRESS 


3.37 LIBRARY/COMPRESS 


This command physically deletes modules that have been logically 
deleted through the LIBRARY/DELETE command. You can rename the 
resulting compressed library with this command. 
Syntax 
LIBRARY/COMPRESS[:(arg[,s])] libr_spec [new_libr_spec] 
arg 
Can be one or more of the following: 
GLOBAL :n | 
MODULES:n 
BLOCKS:n 
libr_spec 
Is the name of the library to be compressed. 
new_libr_spec 
This optional parameter specifies a name for the newly 
compressed library. If you do not specify a name, the new, 
compressed file has the same name as the old one. The old 
file is not deleted after you create (compress) a new one. 
Prompts 
Library? libr_spec [new_libr_spec] 
Arguments 
If you are specifying more than one argument, the arguments 
must be enclosed in parentheses and separated by commas. If 
you are specifying only one argument, the parentheses are 
not necessary. 
GLOBALS:n 
The GLOBALS argument specifies the number of global symbols 
(entry point table entries) to allocate. The default nis 
the number of global symbols allocated in the old library. 


The maximum nis 4096. The value of n is always forced to 
zero for macro and universal libraries. 
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MODULES :n 


The MODULES argument specifies the number of entries to 
allocate in the module name table. The default value is the 
number of entries in the old library. The maximum number of 
module names is 4096. 


BLOCKS :n 


The BLOCKS argument specifies the size of the library in 
256-word blocks. The default size is the size of the old 
library. 
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3.38 LIBRARY/CREATE 


LIBRARY/CREATE creates a library. This command can optionally 
insert one or more modules into the newly created library. 


Syntax 


LIBRARY/CREATE[:(arg[,S])]{/qualifier[s]] libr_spec 
[input_file[,s]] 


arg 
Can be one or more of the following: 
GLOBALS:n 
MODULES:n 
BLOCKS:n 

qualifier 


Can be one or more of the following: 


/{NO]GLOBALS 
/MACRO 
/OBJECT 

/ SQUEEZE 
/UNIVERSAL 


libr_spec 
Is the name of the library to be created. 

input_file 
Specifies the file or files to be used as input to the new 
library file. If no input files are specified, an empty 
library file is created. The default file types are .OBJ 


when creating object module libraries, .MAC when creating 
macro libraries, and .UNI when creating universal libraries. 


Prompts 


Library? libr_spec 
Module(s)? input_file 


LIBRARY/CREATE 


Arguments 
If you are specifying more than one argument, the arguments 
must be enclosed in parentheses and separated by commas. If 
you are specifying only a single argument, the parentheses 
are not necessary. 

GLOBALS:n 
The GLOBALS argument specifies the number of global symbols 
(entry point table entries) to allocate. The default is 512 
for object libraries. The value n is always forced to 0 for 


macro and universal libraries; it can range from 0 through 
4096. 


MODULES:n 
The MODULES argument specifies the number of entries to 
allocate in the module name table. The default value is 
256. mn can be from 0 through 4096. 

BLOCKS:n 


The BLOCKS argument specifies the size of the library in 
256-word blocks. The default size is 100 blocks. 


Qualifiers 
/{NO]GLOBALS 


/NOGLOBALS specifies that global symbols are not to be 
included in the entry point table. 


Use this qualifier if you want to use the same global 
symbols in more than one module. /GLOBALS is the default. 


/ SQUEEZE 
The /SQUEEZE qualifier reduces the size of macro definitions 
by eliminating all trailing blanks and tabs, blank lines, 


and comments from macro text. You must specify an input 
file or files. 


This qualifier has meaning for macro libraries only. 


Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory. 
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This /SQUEEZE qualifier is the equivalent of the LBR /SZ 
qualifier applied to the output library file when using the 
/CR qualifier. 

/MACRO 


The /MACRO qualifier specifies that the library being 
created is a macro library. 


/OBJECT 
The /OBJECT qualifier specifies that the library being 
created is an object module library. This is the default 
and need not be specified. 


/UNIVERSAL 


The /UNIVERSAL qualifier specifies that the library being 
created is a universal library. 
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3.39 LIBRARY/DELETE 


LIBRARY/DELETE deletes modules from a library. (Refer to 
LIBRARY/REMOVE to remove global symbols (entry points) from a 
labrary:) 


Syntax 
LIBRARY/DELETE libr_spec module[,s] 
libr_spec 


Is the name of the library that contains modules’ for 
deletion. 


module 


Is the name of the module for deletion. (The LIBRARY/DELETE 
command will delete up to 15 modules.) 


Prompts 


Library? tlibr_spec 
Module(s)? module 
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3.40 LIBRARY/EXTRACT 


LIBRARY/EXTRACT reads one or more modules from a library and 
writes them to a specified output file. This command can extract 
as many aS eight modules with each execution. If you specify 
more than one module to be extracted, LIBRARY/EXTRACT 
concatenates those modules in the output file. 


Syntax 
LIBRARY/EXTRACT[/qualifier] libr_spec modules[,s] 
qualifier 
/OUTPUT[:filespec] 
libr_spec 
Is the name of the library for the extract (read) operation. 
module 
Specifies the modules that are to be extracted. If you _ do 
not include a list, all modules in the library are extracted 
and concatenated in the output file in alphabetical order. 
You can specify up to eight modules, separated by commas. 
Prompts 
Library? libr spec 
Module(s)? module 
TO? filespec 
Qualifier 
/OUTPUT(:filespec] 
The /OUTPUT qualifier specifies the file to which the 
extracted modules or macros are to be written. If you 
specify /OUTPUT without a filespec, the default is to write 
the modules to your terminal. This makes sense only for 
macro libraries or universal libraries containing text 
modules. 
If you do not include the qualifier, you will be prompted 


To?, to which you are to reply with a filespec. You can 
reply TI: to have the output printed on your terminal. 
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3.41. LIBRARY/INSERT 


This command inserts modules from one or more files into a 
library. 


Syntax 
LIBRARY/INSERT[/qualifier[s]] libr_spec input_filespec[,s] 
qualifier 
Can be one or more of the following: 
/({NO]GLOBALS 
/SELECTIVE_SEARCH 
/SQUEEZE 
libr_spec 
Is the name of the library in which modules will be 
inserted. Any number of files can be specified and each 
file can contain any number of concatenated modules. 
input_filespec 


Is the name of the file that contains the module or modules 
for insertion. 


Prompts 


Library? libr_spec 
Module(s)? module 


Qualifiers 
/{NO]GLOBALS 


/NOGLOBALS specifies that entry points for the specified 
modules are not to be included in the entry point table. 


Use this qualifier if you want to insert global symbols 

having the same name as symbols already in the library file. 

The default, /GLOBALS, does not permit this operation. 
/SELECTIVE SEARCH 

Sets the selective search attribute bit in the module header 


of object modules as they are inserted into an object 
library. You must specify an input file or files. 
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Object modules with this attribute are given Special 
treatment by the Task Builder. Global symbols defined in 
modules with the selective search attribute are not included 
in the Task Builder’s symbol table unless they were 
previously referenced by other modules. 


/ SQUEEZE 
Reduces the size of macro definitions by eliminating all 
trailing blanks and tabs, blank lines, and comments from 


macro text. You must specify an input file or files. 


Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory. 


This qualifier is the equivalent of the LBR /SZ qualifier 
applied to the output file. 
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3.42 LIBRARY/LIST 


This command lists the name of all modules which reside in a 
library. LIBRARY/LIST either displays these names on your 
terminal or writes them in an output file, depending on whether 
you supply a filespec or not. 


Syntax 
LIBRARY/LIST([:filespec][/qualifier] libr_spec 
qualifier 
Can be one or more of the following: 
/BRIEF 
/FULL 
/{NO]NAMES 
filespec 
Is the name of the optional output file. If you do not 
include a filespec as an argument to /LIST, the library is 
listed on your terminal. 
libr_spec 


Is the name of the library that contains the modules to be 
listed. 


Prompts 

Library? libr_spec 
Qualifiers 
/BRIEF 


The /BRIEF qualifier specifies that you want the list to 
include only the module names. This is the default. 


/FULL 


The /FULL qualifier requests a listing of all module names, 
along with a module description including size, date of 
insertion, and module-dependent information. 
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/(NO]NAMES 
The /NAMES qualifier requests a list of modules in the 


library, along with their entry points. The default is 
/NONAMES. | 
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3.43 LIBRARY/REMOVE 


This command removes global symbols (entry points) from a 
library. (Refer to LIBRARY/DELETE to delete object modules from 
a Liorary..) 
Syntax 

LIBRARY/REMOVE libr_spec global[,global[,s]] 


libr_spec 


Is the name of the library that contains global symbols to 
be deleted. 


global 


Is the name of a global symbol for deletion. You can 
Specify as many as 15 global symbols. 


Prompts 


Library? tibr Spec 
Symbol? globals 
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3.44 LIBRARY/REPLACE 


This command replaces a module ina library with a new module of 
the same name and deletes the old module. When a match occurs on 
a module name, the existing module is logically deleted and all 
its entries are removed from the global symbol table. 
Syntax 

LIBRARY/REPLACE[/qualifier[{s]] libr_spec filespec[,s] 
qualifier 

Can be one or more of the following: 

/{NO]GLOBALS 

/SELECTIVE_SEARCH 

/ SQUEEZE 


libr_spec 


Is the name of the library that contains the module for 
replacement. 


filespec 
Is the name of the file or files that contain the new 
modules. If the module to be replaced does not exist in the 
library, LIBRARY performs an insert operation. 


Prompts 


Library? libr.spec 
Module(s)? module 


Qualifiers 

/{NO]GLOBALS 
/NOGLOBALS specifies that entry points for the specified 
modules are not to be included in the entry point table. 
The default is /GLOBALS. 

/SELECTIVE_SEARCH 
Sets the selective search attribute bit in the module header 


of object modules as they are inserted into an object 
library. 
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Object modules with the selective search attribute are given 
Special treatment by the Task Builder. Global symbols 
defined in modules with the selective search attribute are 
only included in the Task Builder’s symbol table if they 
were previously referenced by other modules. 


/SQUEEZE 


Reduces the size of macro definitions by eliminating all 
trailing blanks and tabs, blank lines, and comments from 
macro text. 


Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory in the 
assembler when they are invoked. 


This is the equivalent of the LBR /SZ qualifier applied to 
the input file. 
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3.45 LINK 


LINK invokes the Professional Application Builder (PAB), which 
links object modules and routines from user and system libraries 
to form an executable task. A 


Syntax 


LINK[/qualifier([s] ] 
filespec[/file-qualifier[s]][{,filespec[,s]] 


qualifier 
Can be one or more of the following: 


/ANCILLARY_PROCESSOR[:n] 
/([NO]CHECKPOINT: arg 


SYSTEM 
TASK 
/CODE: (arg[,Ss]) 
EAE 
FPP 
PIC 
POSITION INDEPENDENT 
/COMPATIBLE 


/(NO]CROSS_REFERENCE 
/{(NO]DEBUG[:filespec] 
/ERROR_LIMIT:n 
/(NO]EXECUTABLE[:filespec] 
/FAST_MAP 
/FULL_SEARCH 
/{NO]HEADER 
/(NO]IO_PAGE 
/ LONG 
/MAP[:options-spec] 
/ {NO ]MEMORY_MANAGEMENT|[ :n] 
/OPTIONS[ :options-spec] 
/{NO]PRIVILEGED[:n] 
/{(NO]RECEIVE 
/([NO]RESIDENT_OVERLAYS 
/SAVE 
/{NO]SEGREGATE 
/SEQUENTIAL 
/SHAREABLE[:arg] 
COMMON 
LIBRARY 
TASK 
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/ SLAVE 
/SYMBOL_TABLE[:filespec] 
/[NO]SYSTEM_ LIBRARY DISPLAY 
/(NO]TASK[:filespec] 

/TKB 

/TRACE 

/{NO]WARNINGS 

/WIDE 


filespec 
Is the name of the file containing the object module. 
file-qualifier 


/ {NO ]CONCATENATE 
/DEFAULT_LIBRARY 
/{NO]GLOBALS 
/LIBRARY 


/SELECTIVE_SEARCH 
/OVERLAY_DESCRIPTION 


Prompts 

File(s)? filespec[,s] 
Qualifiers 
/ANCILLARY_PROCESSOR[ :n] 


Identifies the task as an Ancillary Control Processor (ACP). 
The parameter n specifies the base relocation register. 
Acceptable values are 0, 4, or 5. The default is 5. 


In TKB format, apply the /AC qualifier to the .TSK filespec. 


/(NO]CHECKPOINT: arg 
SYSTEM 
TASK 


Specifies that the task is to be (or is not to be) 
checkpointable. Checkpointability of tasks is an important 
part of the operating system’s ability to share resources. 
When a higher priority task seeks access to system memory, 
checkpointable task of lower priority is checkpointed, or 
rolled out to the disk to be stored in its current state 
until the higher priority task exits, whereupon the lower 
priority task returns and takes up where it left off. 


S212 


LINK 


If you do not use the /CHECKPOINT qualifier, your task is 
built noncheckpointable. The default is /NOCHECKPOINT. A 
noncheckpointable task cannot be dislodged by a task of 
higher priority. Therefore, you should always build your 
tasks checkpointable unless you have some important reason 
for not doing so. 


You can specify how the checkpointing of the task is handled 
through the arguments to the /CHECKPOINT qualifier. Your 
task can be checkpointable to the system checkpoint file 


with the SYSTEM option. This is the default. 
LINK/CHECKPOINT and LINK/CHECKPOINT:SYSTEM are equivalent 
commands. 


Tasks built with system checkpointing cannot be checkpointed 
if the system checkpoint file is full. 


You can also reserve checkpoint space for the task as part 
of its own task image file by using LINK/CHECKPOINT:TASK. 


Such tasks are always checkpointable. (If there is_ no 
system checkpoint file, you can only run one copy of such 
tasks. ) 


It should be apparent that the checkpointability of a task 
has an impact on the efficient operation of the entire 
system as well as on the task itself. If the task is built 
noncheckpointable, it can block more important tasks from 
running. If it is built with task checkpointability, 
mass-storage space is reserved that may never be used. If 
it is built with system checkpointability, there may be no 
room for it in the system checkpoint file. 


In TKB format, for /CHECKPOINT:SYSTEM, apply the /CP 
qualifier to the task image file. For /CHECKPOINT:TASK, 


apply the /AL qualifier to the task image file. For 
/NOCHECKPOINT, apply the /-CP qualifier to the task image 
file. 


/CODE:(arg[,S]) 
EAE 
FPP 
PIC 
POSITION_INDEPENDENT 


The /CODE qualifier specifies that the code for the _ task 
relies on certain hardware elements or employs certain 
techniques. See the RSX-11M/M-PLUS and Micro/RSX Task 
Builder Manual for more information. 
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The EAE argument specifies that the task uses the Extended 
Arithmetic Element. In TKB format, apply the /EA qualifier 
to the .TSK filespec. | 


The FPP argument specifies that the task uses the Floating 
Point Processor. This hardware is optional and may not be 
part of your system. In TKB format, apply the /FP qualifier 
to the .TSK filespec. 


The PIC and POSITION_INDEPENDENT arguments are identical and 
Specify that the resident common or library being built is 
position-independent. In TKB- format, apply the /PI 
qualifier to the .TSK or .STB filespec. 


If you want to use more than one argument, enclose them in 
parentheses, separated by commas. 


/COMPATIBLE 


Specifies that the task be built in compatibility mode. 
This means that memory-resident overlay segments are aligned 
on 256-word boundaries’ for compatibility with other 
implementations of the mapping directives. Without this 
qualifier, overlay segments are aligned on 32-word 
boundaries. 


In TKB format, apply the /CM qualifier to the .TSK filespec. 


/{NO]CROSS_REFERENCE 


Specifies that a listing of symbol cross-references is to be 
appended to the Task Builder map file. 


If you include this qualifier, you automatically include the 
/MAP qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. If you 
supply a name, the map file appears in your. current 
directory. 


In TKB format, apply the /CR qualifier to the .MAP filespec. 
/(NO]DEBUG[: filespec] 


Specifies the inclusion of a debugging aid in the _ task 
image. A debugging aid permits you to interrupt the running 
of a task and inspect registers and other memory locations 
at various stages. If you give no filespec, the default is 
LBO:[{1,5]ODT.OBJ, which is ODT, the On-line Debugging Tool, 
a DIGITAL-supplied utility. ODT is incorporated in the task 
you are building. ODT can be used only on tasks written in 
the MACRO-1i1 Assembly Language. 
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See the IAS/RSX-11 ODT Reference Manual for further 
information. 


If you have a user-written debugger, name the file it is in 


when you use this qualifier. This file should be an object 
module. 


In TKB format, apply the /DA qualifier to the .TSK filespec 
if you want to use ODT. If you want to use a user-written 
debugger, apply the /DA qualifier to the input filespec 
naming the debugger. 


/ERROR_LIMIT:n 


Directs the Task Builder to abort LINK after n diagnostics 
errors have been produced. 


In TKB format, apply the /XT:n qualifier to the .TSK 
filespec. 


/(NO]JEXECUTABLE[:filespec] 
See /[NO]TASK. 
/FAST_MAP 


Use this qualifier if you want P/OS to interpret IOT 
instructions in your task as requests to perform fast remap 
operations. When you use the /FAST_MAP qualifier to link 
your task, P/OS interprets all IOT instructions as fast 
remap requests. See the P/OS System Reference Manual for 
details on fast remap operations. 


In TKB format, apply the /FM qualifier to the .TSK filespec. 
/FULL_SEARCH 

Specifies that when processing modules from the default 
object module library, the Task Builder should search all 
co-tree overlay segments for matching definitions or 
references. 

Without this qualifier, unintended global references between 
co-tree overlay segments are eliminated. Definitions of 
global symbols from the default library are restricted in 


scope to references in the main root and the current tree. 


In TKB format, apply the /FU qualifier to the .TSK filespec. 
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/ LONG 


Specifies that the map file produced by the Task Builder 
include additional file information on modules used in the 
task build. The long map does not include file information 
on modules from the system library. 


If you include this qualifier, you automatically include the 
/MAP qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. If you 
supply a name, the map file appears in your current 
directory. 


In TKB format, apply the /-SH qualifier to the .MAP 
filespec. 


/MAP[:options-spec] 


Specifies that you want to produce a memory allocation, or 
map file. If you use /MAP as a command qualifier, without a 
options-spec argument, the map appears in your directory; 
its filename is derived from the name of the first input 
File named in the command line. Its file type is .MAP. 


If you use /MAP with a options-spec argument, either as a 
command qualifier or a filespec qualifier, the map appears 
in your directory with a filename you have given. 


The following qualifiers automatically direct the Task 
Builder to produce a map with special characteristics: 


/CROSS_REFERENCE 
/ LONG 
/SYSTEM_LIBRARY_ DISPLAY 


/WIDE 


You do not need the /MAP qualifier with these qualifiers 
unless you want to add a filespec argument to /MAP. These 
other map-related qualifiers can be used as either command 
or filespec qualifiers, but they have no affect = on 
filenames. | 


In TKB format, the /MAP qualifier corresponds to the second 
position in the list of TKB output files and has the default 
file type .MAP. 
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/{NO]HEADER 


/NOHEADER sets the Task Builder STACK option to 0. If you 
are building a shared region or a driver, you should specify 
this qualifier. If you specify this qualifier, you cannot 
use the STACK option. The default is /HEADER. 


In TKB format, apply the /-HD qualifier to either’ the TSK 
or .STB filespec and specify the STACK=0 option. See 
/SHAREABLE. 


/(NO]IO_PAGE 


/NOIO_PAGE indicates to the Task Builder that the task 185 
over 12K and purposely does not map to the I/O page. This 
qualifier is for building privileged tasks only. The 
default is /IO_PAGE. 


/(NO]MEMORY_MANAGEMENT[ :n] 


Specifies that the task is being built for a system with (or 
without) memory management hardware. Use the /NOMEMORY_ 
MANAGEMENT qualifier when you are building a task on a 
system with memory management to be run on an RSX-11M (or 
RSX-11S) system without the memory management hardware. The 
value n specifies the highest physical address of a task on 
the target system; it can be 28 (the default) or 30. The 
default 1s /MEMORY_MANAGEMENT. 


In TKB format, apply the /-MM qualifier to the .TSK 
filespec. 


/SHAREABLE[ :arg] 
COMMON 
LIBRARY 
TASK 


/SHAREABLE:TASK is the default value and identifies the task 
as a multiuser task. Such tasks permit more than one user 
to share the read-only partition of a single task. When you 
specify /SHAREABLE:TASK, the Task Builder divides the task 
into two regions: region 0 contains the read-write portion 
of the task and region 1 contains the read-only portion of 
the task. When multiuser tasks are installed, multiple 
requests for the task to run cause the system to duplicate 
only the read-write portion of the task for each request 
after the first. The ROPAR option permits you to name the 
portion in which region 1 is to reside. In TKB- format, 
apply the /MU qualifier to the .TSK filespec. 
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/SHAREABLE: COMMON informs the Task Builder that a shareable 
common is being built. You should always use the /NOHEADER 
qualifier with /SHAREABLE:COMMON. If you do not’ specify 
CODES PiC or CODE: POSITION_INDEPENDENT, TKB builds an 
absolute shared common. All program sections in the common 
are marked absolute. ili you specify CODE:PIC or 
CODE: POSITION_INDEPENDENT, all program sections in the 
common are marked relocatable. In either case, the .STB 
file contains all the program section names, attributes, 
lengths, and symbols. The .STB file of a common built 
/SHAREABLE contains all defined program sections. In TKB 
format, apply the /CO qualifier to the .TSK or .STB 
filespec. /SHAREABLE:TASK defaults to /SEGREGATE. 


/SHAREABLE: LIBRARY informs the Task Builder that a shareable 
library is being built. You should always use /NOHEADER 
with /SHAREABLE: LIBRARY. TKB includes only one program 
section in the .STB file. If you do not specify CODE:PIC or 
CODE: POSITION_INDEPENDENT, TKB names the program section 
-ABS, makes the library position-dependent, and defines all 


symbols as absolute. LE you specify CODE+PIC or 
CODE: POSITION_INDEPENDENT, TKB gives the program section the 
Same name as the root segment of the library. TKB forces 


this mame to be the first and only declared program section 
in the library. TKB declares all global symbols in the .STB 
file relative to that program section. In TKB format, apply 
the 7/1 ‘qualifier to the «TSK or .STB tilespec. 


/OPTIONS[ :options-spec] 


Specifies one or more Task Builder options. Use this 
qualifier if * you need to use any of the Task Builder 
options. For full information, on options, see the 


RSX-11M/M-PLUS and Micro/RSX Task Builder Manual. 


You can supply options for this qualifier in two ways: 
supply the filespec of a file containing the options, or 
specify the options themselves. If you do not include a 
filespec with this qualifier, you are prompted for options. 
If you want to enter multiple options, you use a comma after 
each option listed. To list multiple options on individual 
lines, end each line with a comma. 


If you include a filespec with this qualifier, this file 
should contain only the option names, comments, and the 
arguments associated with the options, as shown: 


UNITS=8 

ASG=TT0:7:8 

; COMMENTS, PRECEDED BY SEMICOLON, ALLOWED 
PAR=KROBAR: 50000: 40000 
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This file should only the option statements and comments 
preceded by the semicolon (;). Comments preceded by the 
exclamation point (!) are not accepted in this instance. Do 
not put any slashes in the file. 


Note that the ABORT option is the only means of preventing a 
task build once you have begun issuing commands to the Task 
Builder. A CTRL/Z simply directs the Task Builder to begin 
the task build based on whatever instructions you have 
issued up to that point. Thus, if you want to be sure of 
being able to stop a task build in this way, you must 
include the /OPTIONS qualifier in the LINK command line. 
This assures the availability of the ABORT option. If you 
are typing the command line and make a mistake, specify the 
/OPTIONS qualifier, press RETURN, and enter the ABORT=0 
option. Then press RETURN and the task build aborts. 


/PRIVILEGED[:n] 


Indicates that task is privileged. The argument n specifies 
the base relocation register. Acceptable values are OQ, 4, 
or 5. The default is 5. 


In TKB format, apply the /PR qualifier to the .TSK filespec. 


/{NO]RECEIVE 


Indicates that the task may (or may not) receive messages by 
means of the Executive directive SEND. /RECEIVE is the 
default. 


In TKB format, apply the /SE qualifier to the .TSK filespec. 


/([NO]RESIDENT_OVERLAY 


Enables (or disables) recognition of the memory-resident 
overlay operator (!) in an overlay description file. The 
qualifier is used with the /OVERLAY_DESCRIPTION qualifier 
when the task has memory-resident overlays. The default 1s 
/RESIDENT_OVERLAY. 


In TKB format, apply the /RO qualifier to the .TSK filespec. 


JOAVE 


The /SAVE qualifier specifies that you want to retain the 
indirect command file created by DCL to pass your LINK 
command to TKB. If you include /SAVE in your LINK command 
line, a file named ATLNK.TMP appears in your directory after 
the task build completes. Since this file always has the 
same name, you should give it a name related to the task it 
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builds, such as SHEMPBLD.CMD. Then you can issue a command 
in the following form and duplicate the task build that 
Originally produced the command file: 


S LINK @SHEMPBLD 


This file is also useful for comparing LINK command syntax 
with TKB syntax because it includes the full translation of 
the LINK command into TKB format. 


/([NO]SEGREGATE 


/SEGREGATE causes the Task Builder to order program sections 
alphabetically by name within access code (RO followed by 
RW). If you also specify /SEQUENTIAL, TKB orders’ program 
sections in their input order by access code. 


/NOSEGREGATE is the default. TKB interleaves RO and RW 
program sections. When combined with /SEQUENTIAL, 
/NOSEGREGATE results in a task with program sections 
allocated in input order with its RW and RO sections 
interleaved. If you use /NOSEQUENTIAL and /NOSEGREGATE 
together, which is the default for both, TKB orders program 
sections alphabetically with RW and RO sections interleaved. 


In TKB format, use the /[-]SG qualifier on the .TSK 
filespec. 


/SHAREABLE: TASK defaults to /SEGREGATE. 
/ SEQUENTIAL 


Directs Task Builder to construct a task image from program 
sections in the order in which they appear. Normally, the 
Task Builder finds all program sections referenced in all 
modules in an overlay segment and then builds the task with 
those program sections in alphabetical order. Do not use 
this qualifier to build tasks that rely on alphabetical 
allocation of program sections, such as FORTRAN I/O handling 
modules and FCS modules from SYSLIB. See also /SEGREGATE. 


In TKB format, apply the /SQ qualifier to the .TSK filespec. 


/ SLAVE 


Specifies that the task is to be slaved to a sending task. 
When a slaved task successfully executes the Executive 
directive Receive Data, it is given the [UIC] and TI: of 
the sending task. This qualifier applies only to systems 
with multiuser protection. 
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Slaved tasks cannot be run with a RUN command. They must be 
run by the sending task. 


In TKB format, apply the /SL qualifier to the .TSK filespec. 


/SYMBOL_TABLE[:filespec] 


Directs that a symbol table file be produced. The default 
name is that of the first input file and the default type is 
.STB. The options-spec parameter overrides the defaults. 
This qualifier is used when building shared regions. 


In TKB format, this qualifier corresponds to the third 
position in the list of TKB output files, called the .STB 
filespec. 


/{NO]SYSTEM_LIBRARY_DISPLAY 


Directs the Task Builder to produce a map that includes (or 
does not include) global symbols defined or referenced by 
the task. These symbols are found in LB0:[{1,5]SYSLIB or in 
any shared regions linked to using TKB options. This map is 
usually considerably longer than the default map. The 
information displayed illuminates the contribution that 
SYSLIB or the shared regions make to the task. 


If you include this qualifier, you include the / MAP 
qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. 


If you supply a name, the map file appears in your current 
directory. See the RSX-11M/M-PLUS and Micro/RSX Task 
Builder Manual for more information. 


In TKB format, apply the /MA qualifier to the .MAP filespec. 


/TASK[:taskspec] 
/EXECUTABLE[ :taskspec] 


Specifies a name for the task image file different from that 
of the first input file plus the type .TSK. If used as a 
options-spec qualifier, the task name is derived from _ the 
name of the file to which the qualifier is attached. 
/EXECUTABLE is a synonym. 


In TKB format, this qualifier corresponds to the first 


DOSitiOn. in. “the ist of TKB output. files, called tne .7TSK 
filespec. 
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/NOTASK 
/NOEXECUTABLE 


Specifies that LINK produce no task image file. This 
qualifier is useful when you want to use some facility of 
the Task Builder without building a task, to check for 
unresolved symbol references or make a map, for instance. 
/NOEXECUTABLE is a synonym. 


In TKB format, leave the first position in the list of MTKB 
output filespecs blank, followed by a comma (,). 


/TKB 
Specifies that the default Task Builder be used to build the 
task. This is the default; the qualifier is included for 
completeness. 


You can also invoke the default Task Builder from DCL with 
the command RUN S$PAB. You must follow TKB format if you run 
the default Task Builder in this’ fashion. See the 
RSX-11M/M-PLUS and Micro/RSX Task Builder Manual fora 
description of the TKB command format. 
/TRACE 

Specifies that the task is to be traceable. When you use 
this qualifier, a trace trap occurs on the completion of 
each instruction when the task is run. 

In TKB format, apply the /TR qualifier to the .TSK filespec. 


/{NO]WARNINGS 


/NOWARNINGS suppresses diagnostic messages issued by the the 
Task Builder. Two messages are suppressed: 


n undefined symbols segment "segname" 

and 

Module "modulename" multiply defines P-section "“psectname" 
The default is /WARNINGS. 


In TKB format, use the /[-]NM qualifier on the .TSK 
filespec. 
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/{NO]WIDE 


Specifies that the Task Builder map be printed in 132-column 
format. The default is /NOWIDE. 


If you include this qualifier, you include the /MAP 
qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. If you 


supply a name, the map file appears in your current 
directory. 


In TKB format, apply the /WI qualifier to the .MAP filespec. 


Parameter Qualifiers 


Any input file can have a parameter qualifier applied to it, 
identifying the kind of file that it is. 


/(NO]CONCATENATE 


Identifies the input file as a concatenated object file; 
this is the default. All modules in the file are processed 
to form the task image. /NOCONCATENATE specifies that only 
the first object module encountered is to be processed, 
regardless of how many are present. 


In TKB format, apply the /CC qualifier to an input file 
containing concatenated object modules. 


/ LIBRARY 
Identifies the file as an object module library. This 
qualifier is required for any input library file and is 
prohibited for any other type of file. The default file 


type for object libraries is .OLB. 


The Task Builder searches the library file to resolve all 
undefined global symbol references from files appearing to 
the left of the library file in the LINK command line. The 
Task Builder then extracts any and all modules that resolve 
undefined references and includes them in the task image. 
See also /INCLUDE. 


/INCLUDE:modulel1[:...modulen] 


You can specify as many as eight module names froma library 
using /INCLUDE. You must specify at least one. If you use 
the optional module arguments, the Task Builder takes only 
those modules from the library. The module names are 
defined at assembly time. 
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If you want both to resolve undefined references to global 
symbols and to specify modules, you must use this qualifier 
twice. 


In TKB format, apply the /LB qualifier to an input library 
file for both /LIBRARY and /INCLUDE. 


/DEFAULT_ LIBRARY 


Specifies that the file to which it is appended replace the 
system object module library, LB0O:{1,5]SYSLIB.OLB, as the 
default library that is searched (in order to resolve 
unresolved global references). This qualifier can _ be 
applied to only one file; that file must be an object module 
library having the file type .OLB. 


In TKB format, apply the /DL qualifier to an input library 
file. 


/{NO]GLOBALS 


Specifies that global symbols referenced and defined by the 
input file are (or are not) to be included in the map output 
file. The default is /GLOBALS. 


In TKB format, apply the /-MA qualifier to the input file. 
/SELECTIVE_SEARCH 


Instructs the Task Builder to search the file only for 
undefined references to global symbols. This qualifier is 
most useful when building an Ancillary Control Processor or 
other privileged task that maps into the Executive. If you 
do not specify this qualifier, all of the Executive’s global 
symbol definitions are included in the task build, whether 
or not the file contains undefined references to the global 
symbol. The Executive contains a myriad of modules. In 
these and similar circumstances, this qualifier considerably 
shortens the symbol table search and improves’ system 
performance. 


If you do not use this qualifier, all global symbols’ from 
the input file are included in the task image. 


In TKB format, apply the /-SS qualifier to an input file. 
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/OVERLAY_DESCRIPTION 


Specifies that the input file is an overlay description file 
(type .ODL) that controls the linking of the task. No other 
input file can be specified if you use this qualifier. The 
.ODL file Specifies input files to LINK. 
/OVERLAY_DESCRIPTION can be either a command qualifier or a 
filespec qualifier. 


In TKB format, use the .ODL file as the only input file to 


the right of the equal sign (=) with the /MP qualifier 
applied to the .ODL filespec. 
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3.46 LINK/C81 


This section explains how you can link COBOL-81 object files to 
produce a task image (.TSK file). 


Syntax 
LINK/C81[/qualifier[{s]] filespec[,s] 
LINK/COBOL[/qualifier[s]] filespec[,s] 
qualifier[s] 


Although the format shows them as command qualifiers, you can 
append the following qualifiers to either the command or a file 
specification. When you use the LINK/C81 command, the _ two 
locations are equivalent. 


/{NO]FMS 

/ FMS : NORESIDENT 

/OTS: [NO]RESIDENT 
/{NO]RMS: [NO]RESIDENT 
/{NO]MAP 

/{NO]DEBUG 


filespec[,s] 


Specifies the file or files to be linked. The default file 
type is .SKL. 


The LINK/C81 command links object modules indirectly through 
their associated .SKL files. Therefore, if you include file 
types in any file specifications, you must use .SKL rather 
than .OBJ. Each .SKL file corresponds to an object module 
(.OBJ file) that is included in the task image. Except for 
the file type, the .SKL file and object module have 
identical file specifications. 


You can list any number of .SKL files as input files in any 
order, separated by commas. 


Prompts 


File(s)? filespec[,s] 
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Qualifiers 
/OTS: [NO]RESIDENT 


The /OTS:RESIDENT qualifier includes memory-resident OTS in 
your task image. When you specify /RMS:RESIDENT as well as 
/OTS: RESIDENT, LINK/C81 clusters these two libraries by 
default. If you can take advantage of the clustering 
feature, the resulting task image is smaller and program 
execution speed is improved. You should use /OTS:RESIDENT, 
because the Professional 300 Series only supports 
memory-resident OTS and RMS. 


The /OTS:NORESIDENT qualifier includes the disk-resident OTS 
library in your task image. 


The default is /OTS:NORESIDENT. 
/{[NO]RMS: [NO]RESIDENT 


The /RMS:RESIDENT qualifier creates a reference to the 
shared RMS-11 memory-resident library, RMSRES. This library 
includes input/output support for sequential, indexed, and 
relative file organizations. 


When you specify /OTS:RESIDENT as well as /RMS:RESIDENT, 
LINK/C81 clusters these two libraries by default. If you 
can take advantage of the clustering feature, the resulting 
task image is smaller and program execution speed is 
improved. 


The /NORMS qualifier is equivalent to /RMS:NORESIDENT. 
/{NO]MAP 
The /MAP qualifier causes LINK/C81 to produce a Task Builder 
map file with the file type .MAP. The /NOMAP qualifier 
tells LINK/C81 not to produce a memory map file. 
The default 1s /NOMAP. 
/[NO]DEBUG 
The /DEBUG qualifier tells LINK/C81 to include the COBOL-81 
Symbolic Debugger in your task image. To use this 
qualifier, you must also use the /DEBUG qualifier to _ the 


COBOL command. The /NODEBUG qualifier tells LINK/C81 not to 
include the COBOL-81 Symbolic Debugger in your task image. 
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The default is /NODEBUG. 


/{(NOJFMS 
/FMS :NORESIDENT 


The /FMS qualifier causes LINK/C81 to include Forms 
Management Services (FMS) library support in your task 
image. You must use this qualifier if you call FMS routines 
from your program. 


The /NOFMS qualifier tells LINK/C81 not to include FMS 
support. 


The default is /NOFMS. 
The /FMS:NORESIDENT qualifier causes LINK/C81 to include 
support for a non-memory-resident FMS library in your task 


image. This qualifier is equivalent to /FMS. 


For more detailed information about how to create a #task 
image using LINK/C81, refer to the COBOL-81 RSX-11M/M-PLUS 
User’s Guide. 
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3.47 LOAD 


The LOAD command loads a device driver in the P/OS Operating 


System. Both the driver task image and symbol table file must 
reside in LB:[ZZSYS]. The filenames must be xxDRV.TSK = and 
xxXDRV.STB respectively, where "xx" is the logical device name 
mnemonic. 

Syntax 


LOAD device_mnemonic 
filespec 


Is the logical device name associated with the device 
driver. 


Prompts 


Device mnemonic? device_mnemonic 
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3.48 MACRO 


MACRO invokes the Professional MACRO-11 Assembler (PMA) to 
assemble one or more MACRO-11 assembly language programs into a 
Single relocatable object module suitable for processing by the 
Professional Application Builder (PAB). 


Syntax 


MACRO[/command-qual[s]] 
filespec[/file-qual[s]][{,filespec[,s]] 


command-qual 
Can be one or more of the following: 


/(NO]CROSS_REFERENCE 
/DISABLE: (arg[,s]) 
ABSOLUTE 
BINARY 
CARD FORMAT 
GLOBAL 
LOCAL 
LOWERCASE 
REGISTER DEFINITIONS 
TRUNCATION 
/ENABLE: (arg[,S]) 
ABSOLUTE 
BINARY 
CARD FORMAT 
GLOBAL 
LOCAL 
LOWERCASE 
REGISTER DEFINITIONS 
TRUNCATION 
/(NO]LIST[:filespec] 
/{NOJOBJECT[:filespec] 
/{NO]SHOW[:(arg[,8])] 
ALL 
BINARY 
CALLS 
COMMENTS 
CONDITIONALS 
CONTENTS 
COUNTER 
DEFINITIONS 
EXPANSIONS 
EXTENSIONS 
LISTING_DIRECTIVES 
OBJECT BINARY 
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SEQUENCE_NUMBERS 
SOURCE 
SYMBOLS 
/[NO]WIDE 


filespec 


Specifies one or more input files’ for the MACRO-11 


Assembler. These input files must contain MACRO-11 source 
code. Multiple filespecs must be separated by commas. 
Filespecs must include a filename. If no file type is 
given, the default file type (.MAC) is applied. If the 


parameter qualifier /LIBRARY is used, .MLB is the default 
file type. No wildcards are accepted by MACRO. 


file-qual 
Can be one or more of the following: 


/ LIBRARY 
/PASS:n 


Prompts 

File(s)? filespec[,s] 
Command Qualifiers 
/{NO]LIST[:filespec] 


Specifies whether an assembly listing should be generated. 
The default is /NOLIST, meaning no assembly listing is 
generated. 


If you do not supply a file specification for this 
qualifier, the listing has a filename derived from the name 
of the last source file in the MACRO command, with the file 
type .LST. If you want the listing to have a different 
name, supply the name as an argument to the /LIST qualifier. 
The listing file appears in your default directory. 


If your command line includes the /CROSS_REFERENCE 
qualifier, /LIST is implied and need not be specified. 


If your command line includes listing-control arguments’ to 
either /SHOW or /NOSHOW, /LIST is implied and need not be 
specified. 


The only time you need to use /LIST with /CROSS_REFERENCE or 


/{NO]SHOW is when you want to give the listing file a 
filespec other than the default. 
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/(NO]OBJECT[:filespec] 


Specifies whether an object module should be generated. The 
default is /OBJECT, meaning an object module is generated. 
If you do not supply a file specification, the object file 
has a name derived from the name of the last source file and 
the file type .OBJ. If you want the object file to have a 
different name, give the name as an argument to the /OBJECT 
qualifier. 


You can name the object file after any of the source files 
listed in the MACRO command by uSing /OBJECT as a filespec 
qualifier. If used as a filespec qualifier, /OBJECT cannot 
take a filespec argument. 


The qualifier /NOOBJECT specifies that no object module is 
generated. You can use this qualifier if you want to use 
other facilities of the assembler, to get an assembly 
listing, for instance, without creating an object module. 


/(NO]CROSS_REFERENCE 


Specifies whether a cross-reference listing should be 
generated and appended to the assembly listing. The default 
is /NOCROSS_REFERENCE. 


The cross-reference listing locates all user-defined and 
MACRO symbols that appear in the source program. 


When you specify this qualifier, you are also specifying the 
/LIST qualifier by implication. An assembly listing is 
generated in your directory. If you want to change the name 
of the listing file, you must use /LIST with a file 
Specification in addition to /CROSS_REFERENCE. 


) 


/ENABLE:(arg[,S] 
S]) 


/DISABLE: (arg[, 


These qualifiers override the .ENABL and .DSABL assembler 
directives included in the source program being assembled. 
The .ENABL and .DSABL directives invoke or inhibit various 
aspects of the assembly. Table 3-2 summarizes the arguments 
to /ENABLE and /DISABLE and gives their MACRO-11 
equivalents. There is a default setting for each of these 
directives, even if you do not specify them in your code or 
command line. 


These qualifiers affect the entire assembly. Lig. LOY 
example, your MACRO command includes the qualifier 
/ENABLE:LOWER_CASE, the assembler does not convert any 
lowercase source text to uppercase, regardless of any .DSABL 
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LC or .ENABL LC directives in the source code. The same 
goes for /DISABLE:LOWER_CASE. All -ENABL or .DISABL LC 
directives are ignored. 


If you specify only one argument to /ENABLE or /DISABLE, you 
need not include the parentheses, but if you have more than 
one argument, they must be separated by commas and enclosed 
in parentheses. 


Table 3-2: The Enable and Disable Qualifiers 


Function MACRO Description 


Syntax 


Assembly Functions Disabled by Default 


ABSOLUTE AMA Enabling this function causes 


relative mode addresses (mode 67) 
to be assembled as absolute 
addresses (mode 37). 


BINARY ABS Enabling this function produces 
absolute binary output in FILES-11 
format. 

CARD_FORMAT CDR Enabling this function causes 


source columns 73 and greater to 
be treated as a comment. 


LSB Enabling this function permits the 
disabling or enabling of a local 
symbol block. 


LOWERCASE LC Enabling this function causes 


MACRO-11 to accept lowercase ASCII 
input. The default is to convert 
it to uppercase. 
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Function MACRO Description 
Syntax 
TRUNCATION FPT Enabling this function causes 


floating-point truncation. The 
default is floating-point 
rounding. 


Assembly Functions Enabled by Default 


REGISTER _ REG Disabling this function inhibits 

DEFINITIONS the normal MACRO-11 default 
register definitions. The default 
is 


Under most circumstances, you 
Should use these defaults. 


GLOBAL GBL Disabling this function causes 
MACRO-11 to treat all symbol 
references that are undefined at 
the end of assembly pass 1 as 
undefined symbols. The default is 
to treat all such symbols as 
global symbols. 


/{NO]SHOW[:(arg[,s])] 


These qualifiers override the .LIST and .NLIST assembler 
directives included in the source program being assembled. 
The .LIST and .NLIST directives control the content= and 
format of the assembly listing. Table 3-3 Summarizes the 
arguments to /SHOW and /NOSHOW and gives their MACRO-11 
equivalents. There is a default setting for each of these 
directives, even if you do not specify them in your code or 
command line. 


These qualifiers affect the entire assembly. ity. or 
example, your MACRO command includes the qualifier 
/SHOW: COMMENTS, the assembly listing includes all comments, 
regardless of any .NLIST COM or .LIST COM directives in the 
source code. The same goes for /NOSHOW:COMMENTS. All .LIST 
COM or .DISABL COM directives are ignored. 
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If you specify only one argument to /SHOW or /NOSHOW, you 
need not include the parentheses, but if you have more than 


one argument, 


they must be separated by commas and 
in parentheses. 


enclosed 


/SHOW implies /LIST, but if you want the listing file to 


have a name 
/UIST. 


other 


the 


default, you must still use 


Table 3-3: The /SHOW and /NOSHOW Qualifiers 


Function 


MACRO 
Syntax 


Description 


Listing Functions Disabled by Default 


EXPANSIONS 


BINARY 


LISTING__DIRECTIVES 


SEQUENCE_ NUMBERS 


COUNTER 


OBJECT_ BINARY 


ME 


MEB 


LD 


SEQ 


LOC 


BIN 


Enabling this function causes 
MACRO-11 to include all macro 
expansions in the listing. 


Enabling this function causes 
MACRO-11 to list only those 
macro expansions that generate 
binary code. This is a subset 
of EXPANSIONS. 


Enabling this function causes 
MACRO-11 to list all listing 
control directives without 
arguments (these are the 
listing directives that alter 
the listing level count). 


Disabling this function 
suppresses the inclusion of 
sequence numbers in the 
listing. Sequence numbers are 
replaced by tabs. 


Disabling this function 
suppresses the location 
counter field and does not 
replace it with a tab. 


Disabling this function 
suppresses the listing of 
generated binary code and does 
not replace it with a tab. 
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Function MACRO Description 
Syntax 
EXTENSIONS BEX Disabling this function 


Suppresses the listing of 
binary extensions, that is, 
all binary code that will not 
fit on the first line. This 1s 
a subset of OBJECT.__BINARY. 


SOURCE SRC Disabling this function 
Suppresses the listing of 
source lines. 


COMMENTS COM Disabling this function 
Suppresses the listing of 
comments. This is a subset of 
SOURCE. 


DEFINITIONS MD Disabling this function 
Suppresses the listing of 
macro definitions and repeat 
range expansions. 


CALLS MC Disabling this function 
Suppresses the listing of 
macro calls and repeat range 
expansions. 


CONDITIONALS CND Disabling this function 
suppresses the listing of 
unsatisfied conditional 
Coding. 


CONTENTS TOC Disabling this function 
suppresses the listing of 
table of contents during 
assembly pass 1. The full 
assembly listing is still 
prepared during assembly pass 
a 


SYMBOLS SYM Disabling this function 
suppresses the listing of the 
symbol table resulting from 
the assembly. 
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/{NO]WIDE 


Specifies whether you want the assembly listing in wide or 
narrow format. As supplied, the default is /WIDE, also 
called line printer format. /NOWIDE is sometimes called 
teleprinter format. 


This qualifier overrides any .LIST TTM or .NLIST TTM 
directives included in your source program. 


Parameter Qualifiers 
/PASS:n 


Specifies that the file thus qualified is only to be 
assembled during the pass specified. The assembler makes 
two passes; n can be either 1 or 2. 


/LIBRARY 


Specifies that the file thus qualified is a macro library. 
The default file type is .MLB. A user macro library file 
must be specified in the command line before any _ source 
files that use the macros defined in the library. A library 
may not be the last file named in the command line. 
Remember that the system macro library has the type .SML. 
If you are referencing this library, you must explicitly 
state the type. 
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3.49 MAIL 


With PRO/DECnet only, the MAIL command invokes the PRO/DECnet 
Mail Utility. This utility allows you to send or read messages 
to or from other users on your system, or to another’ system 
connected by PRO/DECnet. For a complete description of the Mail 
Utility see the PRO/DECnet User’s Guide. 

Syntax 


MAIL 


Prompts 


None 


Qualifiers 


None 
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3.50 MOUNT 


This command declares a volume (and therefore the files or data 
it contains) to be logically known to the system, on-line, and 
available for use. 
Syntax 

MOUNT[/qualifier] device: [volumelabel] 
qualifer 


Can be any combination of the following: 


/ FOREIGN 
/ SHOW 


device: 
Is the device on which you want to mount the volume. 
volumelabel 
Is the name of the volume. If the volume name does not 
match the volumelabel parameter, then DCL displays an error 
message and does not mount the device. 
Prompts 
Device? device: [{volumelabel] 
Qualifiers 


/ FOREIGN 


Specifies that the volume being mounted is not in = standard 
P/OS (FILES-11) format. 


/ SHOW 


Displays the volume label after mounting the volume. 
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3.51 PASCAL 


This command invokes the PRO/Tool Kit PASCAL compiler to compile 
one or more PASCAL source programs. 


NOTE 


Please refer to the language documentation for 
additional information. 


Syntax 

PASCAL[/qualifier[s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/([NO]CHECK[ :arg] 

ALL 

BOUNDS 

SUBRANGE 

POINTER 

STACK 

DIVIDE 

CASE 
/CODE:arg 

FPP 

EIS 
/{NO]DEBUG: TRACE_BACK 
/{NO]LIST[:filespec] 
/{NO]MACHINE_CODE[:filespec] 
/{NO]OBJECT[:filespec] 
/{NO]STANDARD 
/({NO]XRAY 
/[NO]LOG 


filespec 
Is the name of a PASCAL source file. 
Prompts 


Files? filespec[,s] 
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Qualifiers 
/(NO]CHECK[ :arg] 


The /CHECK option controls run-time checking. 


Arguments: 

ALL enables all values (default) 

BOUNDS enables array bounds checking 

CASE enables CASE statement expression checking 
DIVIDE enables divide by zero checking 

POINTER enables NIL pointer checking 

STACK enables stack overflow checking 


SUBRANGE enables subrange checking 


/CODE:arg 


The /CODE option controls whether the code generated by Tool 
Kit PASCAL uses FPP instructions to perform floating point 
operations or EIS instructions to simulate floating point 
operations with subroutine calls. 


Arguments: 
FPP generates FPP instructions (default) 
EIS generates EIS instructions 


/{NO]DEBUG:TRACE_BACK 


The /DEBUG option controls whether Tool Kit PASCAL generates 
code that tracks the relationship between the lines in the 
program source code and the current position in the 
executing program. When /DEBUG is enabled, run-time error 
messages indicate the line which caused the error and_ the 
currently active procedure and function invocations. 


/(NO]JLIST[: filespec] 


The /LIST(:filespec] option controls whether Tool Kit PASCAL 
generates a program listing file. The default 1s /NOLIST; 
thus compiler error messages appear on your’ terminal. If 
you specify /LIST and do not supply a file specification, 
the default is file.LST, where file is the name of the first 
input file. 
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/(NO]MACHINE_CODE[:filespec] 


The /MACHINE_CODE option controls whether Tool Kit PASCAL 
generates a MACRO-11 source file containing the assembly 
language code for the program. The default is 
/NOMACHINE CODE. 


The default name of the object file created by PASCAL is the 
last-named source file with the file type .MAC. If you want 
the object file to have a different name, supply the name as 
an argument to the qualifier. You can examine or assemble 
this file. 


Also, you must not specify the /OBJECT and /MACHINE_CODE 
qualifiers together on the same command line. 


/{NOJOBJECT[:filespec] 


Determines whether or not an object module is generated by 
the compiler. The default is /OBJECT, which does create a 
module. The default name of the object file created by 
PASCAL is the last-named source file with the file type 
OBJ. If you want the object file to have a different name, 
supply the name as an argument to the /OBJECT qualifier. 


/NOOBJECT specifies that no object module is created. You 
can use the /NOOBJECT qualifier to get a compiler listing 
file to check for errors without generating object code. 


You must not specify the YOBIECT and /MACHINE_CODE 
qualifiers together on the same command line. 


/{NO]STANDARD 


The /STANDARD option flags any uses of language features not 
supported by the ISO PASCAL standard. The default is 


/NOSTANDARD. 
/{NO]XRAY or /[NO]LOG 
The /XRAY or /LOG option causes Tool Kit PASCAL to display 


its progress as it compiles a program. The default is 
/NOXRAY and /NOLOG. 
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3.52 PHONE 


With PRO/DECnet only, the PHONE command invokes the PRO/DECnet 
Phone Utility, which allows you to communicate with other users 
on your system or another system connected to your system by 
PRO/DECnet. For a complete description of the Phone Utility, 
including information on the PHONE command line, see the 
PRO/DECnet User’s Guide. 

Syntax 

PHONE [phone-command] 
Prompt 


None 
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3.53 PRINT 


This command allows printing to the local printer. The current 
default settings will be used to print the file(s). 
Syntax 
PRINT filespec[,s] 
filespec 


The name of the file(s) to print. 


Prompt 


File(s)? filespec[,s] 
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3.54 PRINT/REMOTE 


PRINT/REMOTE is available only with PRO/DECnet. PRINT/REMOTE 
directs an existing file on a remote node to a line printer for 
printing. If the file you want to print is not on that node, you 
may want to use the COPY command with a /PRINT qualifier. 
Syntax 

PRINT/REMOTE[/qualifier[,s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/ LOG 
/(NO]WARNINGS 


filespec 


The file specification (including node specification) for 
each file to be queued for printing. 


Prompt 


File(s)? fFilespec[,s] 


Qualifiers 
/ LOG 


The /LOG qualifier specifies that the names of files printed 
are to be displayed as the operation is performed. 


/{NO]WARNINGS 
The /NOWARNINGS qualifier specifies that the "No such file" 


error messages should not be displayed when the input files 
do not exist. 
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3.55 PURGE 


PURGE deletes all but the latest versions of files, and releases 
the storage space that the deleted files occupied. 


Syntax 

PURGE[/qualifier[{s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/{[NO]LOG 
/KEEP:n 

/DATE:dd-mmm-yy 

/SINCE: dd-mmm-yy 

/ THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 

/NOWARNINGS 


fFilespec 


Is the name of the file, whose old versions are to be 
deleted. You must have delete access to the file. 


Prompts 
File(s)? Filespec[,s] 
Qualifiers 


/{NO]LOG 


Specifies that the files deleted by PURGE be listed on your 
terminal. The default is /NOLOG. 


/KEEP:n 
Specifies that the n latest versions of a file be retained. 


If you do net. use: Chis qudlitier, all versions but the most 
recent of a given file are deleted. That is, the default 


form of the command includes the qualifier /KEEP:1. With 
the qualifier explicitly stated, all but then highest 
numbered versions are deleted. PURGE assumes that the 
version numbers of files are in sequential order, for 
example: 
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FILE bIS+4 PIbbl.~b1S; 3° PILEL.GIS;2 FILET. LIS 4 


and that there are no versions misSing from the sequence, 
for example: 


FILEL:LIS?20 FILEL.LIS¢1> PILEL<LIS;i4 


If more than one filespec is given with the /KEEP qualifier, 
all but the latest n versions of all files listed are 
deleted. 


/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the PURGE 
command to affect only files created by the value specified 
for /DATE. 


/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the PURGE 
command to affect only files created on or since the value 
specified by /SINCE. 


/ THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the PURGE 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE:dd-mmm-yy/THROUGH : dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the PURGE command to affect only files 
created within that range. 


/TODAY 


The /TODAY qualifier specifies that you want the PURGE 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the PURGE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 
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/NOWARNINGS 
The /NOWARNINGS qualifier specifies that the "No such _ file" 


error message should not be displayed when the input files 
do not exist. 
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3.56 REMOVE 


This command removes the name of a task from the System Task 
Directory. The task is no longer installed. REMOVE/REGION takes 
the name of a region out of the Common Block Directory and_ the 
partition list. 
Syntax 
REMOVE[/qualifier] taskname 
qualifier 
/ REGION 
taskname 
Is the name of the task to be removed from the System Task 
Directory. If you want to remove a region, specify the 
/REGION qualifier. 
Prompts 
Taskname? taskname 
Qualifier 


/ REGION 


Specifies that you want to remove a region from the Common 
Block Directory. 
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3.57 RENAME 
This command changes the name, type, or version number of an 
existing file. 
Syntax 

RENAME[/qualifier[s]] old_filespec new_filespec 
qualifier 

Can be one or more of the following: 


/DATE:dd-mmm-yy 

/SINCE: dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 

/EXCLUDE: filespec 

/NOWARNINGS 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


JLOG 
/NEW_VERSION 


old_filespec 
is the filename prior to renaming. 

new_filespec 
Is the desired new name of the file. If you want to specify 
a new directory for the file, you can only specify a 


directory that exists on the same volume. This is because 
the file is not actually copied. 


Prompts 


Old file name? old_filespec 
New file name? new_filespec 
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Qualifiers 
/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the RENAME 
command to affect only files created by the value specified 
for /DATE. 


/SINCE: dd-mmm-yy 


The /SINCE qualifier Specifies that you want the RENAME 
command to affect only files created on or since the value 
specified by /SINCE. 


/ THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the RENAME 
command to affect only files created on or before the value 
Specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the RENAME command to affect only 
Files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the RENAME 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 
The /EXCLUDE qualifier specifies that you want the RENAME 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "x" 
wildcard. 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the old_filespec does not exist. 
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Additional Qualifiers Available with PRO/DECnet 
Command Qualifiers 
/LOG 


Specifies that the names of files renamed are to be 
displayed as the operation is performed. 


File Qualifiers 

/NEW_VERSION 
The NEW_VERSION qualifier specifies that the output files 
will be created with a version number higher than any 
existing files of the same name in the directory. 


/NEW_VERSION must appear after the file specification in the 
command line. 
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3.58 REPLY 


When the P/OS Broadcast application is installed on your’ system 
and the target systems, the REPLY command allows you _ to 
communicate with system users. 
Syntax 
REPLY({/qualifier] "message-text" 
message-text 
Specifies the message to be displayed. When a message 
contains more than one word, enclose the message in 
quotation marks. 
qualifier 
/NODE 
Prompt 
Message? 
Qualifiers 
/NODE[=(node name[,...])] 
Sends a message to the local system only. The optional 
parameter list allows you to specify which nodes will 


receive the message. The default is to send the message to 
all workstations connected to the system. 
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3.59 RUN installed task 


If the task is installed, RUN initiates its execution. You can 
use RUN to initiate the execution of installed tasks ona 
schedule by creating entries in the system clock queue. 
Syntax 
RUN[/qualifier[{s]] taskname 
qualifier 
Can be one or more of the following: 
/COMMAND: "taskcommand" 
/DELAY:nu 
/ INTERVAL: nu 
/SCHEDULE:hh:mm:ss 
/SYNCHRONIZE:u 
taskname 
Is the name of the task that RUN will execute. 
Prompts 
Task? taskname 
Qualifiers 
/COMMAND: "taskcommand" 
Use the /COMMAND qualifier to pass a command to the task you 
are running. The command must be inside the "quotes" and 
not more than 40 characters long. For example, the command 


RUN/COMMAND: "PIP /LI" SPIP 


runs PIP and then passes the /LI qualifier to it. This 
results in a directory listing. 


To pass an MCR-format command (if the task will accept it), 
you must precede the command with the taskname followed by a 


Space. For example: 


RUN/COMMAND: "CMP TI:=filei.dat,file2.dat" SCMP 


g2¢6° 
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The time-oriented qualifiers to RUN create entries in the system 
clock queue. The contents of the clock queue can be displayed 
with the command SHOW CLOCK_QUEUE. 


/ DELAY :nu 


Specifies that the task be run after the stated amount of 
time passes. The argument nu specifies the amount of the 
delay as a number of units. The value nis the number of 
units and the value u is the time unit, as follows: 


T - Ticks 
S - Seconds 
M - Minutes 
H - Hours 


Your system has a programmable clock. The frequency of this 
clock is 64 Hz, which results ina tick length of 1/64th of 
a second. 


Acceptable values for these units are as follows: 


T - Any positive value to a maximum of 15 bits, or 
32767 


S - Any positive value to a maximum of 15 bits, or 
321673 


M - The maximum value is 1440. 
H - The maximum value is 24. 


The system always waits at least one interval. If you 
specify 0, the system treats it as al. 


/INTERVAL: nu 


Specifies that the task is to be run at regular intervals. 
The argument nu specifies the interval as a number of units 
of time. The value n is the number of units and the value u 
is the unit, as follows: 


- Ticks 
-~ Seconds 
Minutes 
- Hours 


meaner 
i 


See the /DELAY qualifier for a detailed description of these 
units. 
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/SCHEDULE:hh:mm:ss 

Specifies that the task be run at a particular time of day. 
/SYNCHRONIZE:u 

Specifies that the execution of the task be synchronized on 


the next occurrence of a particular clock unit. The value u 
is the time unit, as follows: 


T - Ticks 
S - Seconds 
M - Minutes 
H - Hours 
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3.60 RUN uninstalled task 


This command checks to see if the task is installed. If the task 
is not installed, RUN installs the task image, runs it, and 
removes the name of the task from the System Task Directory when 
task execution completes. In the case when a task image is not 
installed, RUN actually comprises the INSTALL, RUN, and REMOVE 
commands. 

Syntax 

RUN[/qualifier[s]] [$] filespec 
qualifier 


Can be one or more of the following: 


/COMMAND: "taskcommand" 
/TASK_NAME:taskname 


[$] filespec 
Is the name of the uninstalled task image. The dollar’ sign 
(S$) directs the system to search first for the file in the 
PRO/Tool Kit application directory. You can display this 
directory by typing SHOW LOGICAL APPLSDIR. 

Prompts 
Task? [$]filespec 

Qualifiers 

/COMMAND: "taskcommand" 
Use the /COMMAND qualifier to pass a command to the task you 
are running. The command must be inside the "quotes" and 
not more than 40 characters long. For example, the command 


RUN/COMMAND: "PIP /LI" SPIP 


runs PIP and then passes the /LI qualifier to it. This 
results in a directory listing. 


To pass an MCR-format command (if the task will accept it), 
you must precede the command with the taskname followed by a 
Space. For example: 


RUN/COMMAND: "CMP TI:=filei.dat,file2.dat" SCMP 
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/TASK_NAME:taskname 


Specifies the name under which the task is to be run. The 
Gefault is to run the task under a name derived from the 
name of the terminal from which the RUN command was issued. 


Task names are restricted to six Radix-50 characters. The 
Radix-50 character set consists of the 26 uppercase letters, 
the 10 numerals, the period (.), and dollar sign (S$). 
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SET [DAY]TIME 


This command sets the current date and time. 


Syntax 


SET [DAY]TIME: [dd-mmm-yy] [hh:mm] 


dd-mmm-yy 


Specifies the date. You can enter the date in either of two 


formats: 


dd-mmm-yy 


mn/dd/yy 


Where dd is the number of the day, mmm is 
the first three characters of the name of 
the month, and yy is the number of the 
year (relative to 1900). 


Where mn is the number of the month, dd is 
the number of the day, and yy is the 
number of the year (relative to 1900). 


Regardless of the format you choose, the date is displayed 
in the first format. 


hh:mm[:ss] 


Is the time to which the system will be set (24-hour format) 


in the form 14:35. 


Prompts 


Time? hh:mm 


Date? dd-mmm-yy 
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3.62 SET DEFAULT 


The SET DEFAULT command establishes the default directory and/or 
device from the current default. You can set the default for the 
directory, the device, or both. 


If you set default to a nonexistent device or directory, no error 
messgage is displayed. However, when you try to perform an 
operation in the nonexistent directory or on the nonexistent 
device, an error message appears. 
Syntax 

SET DEFAULT [device:][dirspec] 
device: 

Is the device name. 
dirspec 


is the directory name enclosed in square brackets, for 


example: [MYDIR]. 
Prompts 
Device and/or directory? [device: ][dirspec] 
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3.63 SET DEVICE 


SET DEVICE establishes certain attributes for the specified 
device. 


Syntax 
SET DEVICE:ddnnn: /device-attribute[s] 


ddnn 


Specifies the device for which attributes are to be set. 
When the one-line form of the command is used, the parameter 
is ddnnn: preceded by a colon (:) at the end of the word 
DEVICE. 

device-attribute 


Can be one or more of the following: 


/{NO]LOWERCASE 
/WIDTH:n 


Prompts 


Device? ddnnn: 
Device attribute? qualifier 


Device Attributes 

/ {NO ]LOWERCASE 
The /LOWERCASE attribute sets a terminal or line printer’ so 
that lowercase characters are not converted to uppercase for 
printing. 
The /NOLOWERCASE attribute sets a terminal or line printer 
so that lowercase characters are converted to uppercase for 


printing. This is the default. 


You can use the SET TERMINAL/LOWERCASE command to set TI: 
in this fashion. 


/WIDTH:n 


Sets the size of a device’s I/O buffer. The value of n 
(octal) is the length in characters of a line on the device. 
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For terminals, n must be greater than 2 and not greater than 
255% The terminal driver does not discard excess 
characters, but puts them ina record of their own. That 
is, excess characters appear one line below the line in 
which they should appear. 
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3.64 SET FILE 


SET FILE establishes certain file attributes. You can change an 
end-of-file marker, direct an entry in one directory to point to 
a file in another directory, remove an entry from a directory, or 
truncate files to their actual length. 


Syntax 


SET FILE [/qualifier[s]] filespec[,s] [/qualifier[s]] 


qualifiers 


Command Qualifiers 
/ENTER: synonym_filespec 
/NOWARNINGS 

/ REMOVE 

/TRUNCATE 

File Qualifier 


/END_OF_FILE: (BLOCK:n,BYTE:n) 

filespec 
Identifies the file or files you want the operation to 
affect. 


Prompt 


File(s)? filespec[,s] 
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Qualifiers 
/ENTER: synonym_filespec 


Adds a directory entry to a directory. Use this qualifier 
to refer to a file by more than one name, or to place the 
same file in more than one directory. The synonym_filespec 
is the new directory entry, which is the name of the file, 
including its new directory location. If many users’ need 
the same file, this qualifier can save a lot of disk space. 
If a file of the name you specify already exists, the new 
file has a version number one higher’ than that of the 
original file. 


If you specify more than one file with this qualifier, the 
synonym_filespec points to all those files. In effect, the 
files are concatenated. If you omit any field of the 
synonym_filespec, the corresponding field in the parameter 
File specification is *.*;%, 


/NOWARNINGS 
Suppresses error messages from the operation. 
/ REMOVE 


Removes a directory entry from a directory. The /REMOVE 
qualifier is the opposite of the /ENTER qualifier. 


You can use this qualifier to delete synonyms created by the 
/ENTER qualifier. You can also use it to eliminate 
directory entries that point to nonexistent files. If you 
remove the last entry for a file, it can only be found with 
the VERIFY (VFY) utility. 
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/TRUNCATE 


Enables you to recover unused disk space. When P/OS creates 
a file, it allocates file space in multiple units. The 
system, however, uses these blocks one at ae time. This 
means that files often include unused blocks. 


Issue the command DIRECTORY/FULL to check the number of 
blocks used and allocated for a file. In the listing, two 
numbers in the form x./y. indicate the number of blocks 
actually used (x) and the number of blocks allocated (y). 
If y is greater than x, more blocks than necessary are 


allocated. Because EXTEND access allows the system to 
change the size of a file -- in response to a user’s request 
or the needs of a task -- the extra blocks may be of limited 


use and may be truncated without causing problems. 


In some cases, the presence of the extra, allocated but 
unused, blocks may speed execution of a task. 


/END_OF_FILE[:(BLOCK:n,BYTE:n) ] 


You can specify only one file with this qualifier. Use 
/END_OF_FILE to specify the location of a file’s end-of-file 
pointer. This helps when a file contains useful information 
but its end-of-file pointer is wrong, preventing you from 
obtaining the information. 


The end-of-file pointer is an unprotected file attribute. 
If you are the file owner or a privileged user, you do not 
need READ or WRITE access to read or change this attribute. 
If you are classified group or world for the file, you need 
READ access to read the attribute and WRITE access to change 
pls ae 


If you do not specify values for BLOCK and BYTE, the system 
puts the end-of-file pointer after the last byte of the last 
block allocated to the file. 


For BLOCK, the argument n specifies the number of the block 
in which the end-of-file pointer is to be placed. Usually, 
the pointer cannot be placed beyond the highest number of 
blocks allocated to the file. However, if all bytes of the 
allocated blocks are used, the pointer can be placed in the 
first byte of the next block. For example, if the number of 
blocks allocated is 22, you would specify (BLOCK:23,BYTE:0). 


For BYTE, the argument n specifies the location of the first 


unused byte of the specified block. The maximum value for 
BYTE is 511 decimal. 
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3.65 SET HOST 


With PRO/DECnet only, SET HOST invokes the Remote DECnet Terminal 
application (available with PRO/DECnet). This allows your 
Professional node to communicate with a remote host, performing 
terminal operations as though it were local to the host. The 
host must support terminal emulation from remote nodes. You 
cannot set host to another Professional Computer. 

syntax 

SET HOST node_name 


node-name 


Is the name of the node to which you want to connect. 


Prompts 


Host? node_name 


Qualifiers 

None 
To disconnect from a VMS or RSX host computer, either log off of 
the host, or press the <MAIN SCREEN> or <EXIT> key. The 


preferable method is to log off the host computer. 


To disconnect from a TOPS-10 or TOPS-20 host computer, log off of 
the host, and then press the <MAIN SCREEN> or the <EXIT> key. 


Once you have exited from the host computer, press <RESUME> to 
return control to your node. 


Refer to the PRO/DECnet User’s Guide for information about 
differences in processing during terminal emulation. 
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3.66 SET PRIORITY 


This command alters the priority of an active task. 
Syntax 


SET PRIORITY:n taskname 


n 
Specifies the new priority you want to assign to the task. 
Priority mumbers are in the range of from 1 through 250. 
The value n is octal or decimal. Append a decimal point to 
indicate that it is a decimal number. 

taskname 
Is the name of the task whose priority is to change. 

Prompts 
Priority number? n 
Taskname? taskname 
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3.67 SET PROMPT 


SET PROMPT allows you to customize the prompts at your’ terminal. 
You can specify a prompt string other than the S$ prompt used in 
DCL. 
Syntax 

SET PROMPT([=string] 


string 


Specifies the string to replace the default DCL prompt 


string (S$). The string can consist of more than one 
character. All valid ASCII characters can be used in the 
string. 


In order to include spaces or lowercase letters in your 
string, you must enclose the string in quotation marks. 
Otherwise, letters are automatically converted to uppercase, 
and leading and trailing spaces are removed. 


If no string is specified with the SET PROMPT command, the 
DCL default prompt string ($) is restored. 


Prompt 


None 
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SET PROTECTION 


The SET PROTECTION command establishes the protection status of a 
file. Protection status determines which categories of user may 
access a file and what each kind of user may do to the file. 


Syntax 


SET PROTECTION[/qualifier[s]] filespec[,s] (code) 


qualifier 
Can be one or more 
/DATE: dd-mmm-yy 


/SINCE:dd-mmm-yy 
/ THROUGH : dd-mmm-yy 


of the following: 


/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 


/ TODAY 
/EXCLUDE: filespec 
/{NO]WARNINGS 


With PRO/DECnet DCL extensions, the following qualifiers are also 


available: 


/OWNER[ :uic] 


filespec 
Is the name of the 


(code) 


file to be protected 


There are four kinds of users: 


SYSTEM 


OWNER 


GROUP 


WORLD 


The operating system itself, and 
privileged users, those with group 
numbers of 10 or less. 


The user whose UIC the file was created 
under. 


All users whose group number the file was 
created under. 


All other users. 


There are also four kinds of access to files: 
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READ The user or user’s tasks can read, copy, 
print, type or run the file (if it is a 
task image). 


WRITE The user or user’s tasks can write new 
data to the file. 


EXTEND The user or user’s tasks can increase the 
amount of disk space allocated to the 
file. 

DELETE The user or user’s tasks can delete the 
file. 


The system default protection code is expressed as follows: 


(SYSTEM: RWED, OWNER: RWED, GROUP: RWED, WORLD: RWED ) 


Under this code, the system and privileged users have _ full 
access to your files. You, as well as others with your 
group number, also have full access to your files. Other 
nonprivileged users can only read your files. If no other 
protection is specified, all files have this protection. 


If you want to protect a particular file differently from 
the current system default, name in the protection code only 
the user group whose access rights you want to change and 
the access form you want to grant to that group. If you 
want to deny all access to a group, simply name the group 
and omit the colon (:) and the code for the access form. 


If any of the parameters (System, Owner, Group, World) 15s 
eliminated from the code, SET PROTECTION does not change the 
value of that parameter. If the parameter is listed with no 
code (SYSTEM:R,OWNER: RWED,GROUP,WORLD), SET PROTECTION 
assigns no access to that parameter. 
Prompts 

File? fFilespec[,s] 

- Qualifiers 

/DATE:dd-mmm-yy 
The /DATE qualifier specifies that the SET PROTECTION 


command affect only files created by the value specified for 
/DATE. 


Cia ee 
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/SINCE: dd-mmm-yy 
The /SINCE qualifier specifies that the SET PROTECTION 
command affect only files created on or since the value 
specified by /SINCE. 

/THROUGH: dd-mmm-yy 
The /THROUGH qualifier specifies that the SET PROTECTION 
command affect only files created on or before the value 
specified by /THROUGH. 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers combined specifies that 
the SET PROTECTION command affect only files created within 
the given range. 

/ TODAY 
The /TODAY qualifier specifies that the SET PROTECTION 
command affect only files created on the day the command is 
issued. 

/EXCLUDE: filespec 
The /EXCLUDE qualifier specifies that you want the SET 
PROTECTION command not to affect certain files. The 
filespec argument to /EXCLUDE can contain wildcards, but the 
filespec must contain a version number, either explicitly or 
as the "*" wildcard. 


/NOWARNINGS 


This qualifier suppresses display of "No such file" error 
messages when the input files specified do not exist. 


Additional Qualifiers Available with PRO/DECnet 
Command Qualifiers 

None 

File Qualifiers 

/OWNER:uic 


Sets the ownership of a file to the specified UIC, in _ the 
form [ggg,mmm]. 
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3.69 SET PROTECTION/DEFAULT 


Establishes the default protection for all files created during 
the current login session. The protection for a file limits the 
type of access available to other system users. 
Syntax 

SET PROTECTION: protection_code/DEFAULT 


protection_code 


Is the protection code to be given to the files created 
during your current login session. 


The code takes the following format: 


(({SYSTEM[:n]],[OWNER[:n]],[GROUP[:n]],[WORLD[:n]]) 


where: 
SYSTEM Is the system level protection code. 
OWNER Is the owner level protection code. 
GROUP Is the group level protection code. 
WORLD Is the world level protection code. 
n Is the type of access that is to be allowed. 


The value for n can be any or all of the following values, in any 
order: 


R Read allowed. The user may read, copy, print or 
type (scroll through) the file, and if it is a 
task, run it. 


W Write allowed. The user (or the user’s 
application) can add new information to the file. 


E Extend allowed. The user, or the user’s tasks, can 
change the amount of disk space allocated to 
the file. 

D Delete allowed. The user (or the user’s 


application) can delete the file. 


Only those categories that are specified are allowed; all others 
remain protected. If you enter one of the categories, but do not 
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Specify a value for n, no access is allowed at that level. In 
addition, if a category is not entered, then access is denied for 
that category. For example, SET DEFAULT PROTECTION: (OWNER: RWED) 
allows only owner access to the files created. 


NOTE 
Your default file protection is set during the 
login process. You may specify a default file 
protection that is restored during the login 
process with Environment Services. 


Prompts 


Protection code? protection_code 
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3.70 SET PROTECTION/NODEFAULT 


Removes, your currently defined default file protection. (See 
SET PROTECTION/DEFAULT.) Any file created during the current 
login session will have the file protection of: 

(SYSTEM: RWED, OWNER: RWED, GROUP: RWED, WORLD: RWED) 
Syntax 

SET PROTECTION/NODEFAULT 


Prompts 


None 


3-174 


SET TERMINAL 


3.71 SET TERMINAL 


This command sets various attributes of the terminal. 
Syntax 

SET TERMINAL[:ttnnn:] attribute[/attribute[s] ] 
ttnnn 

Is the number of the terminal. 
attribute 

Can be one or more of the following: 

Group 1: Common Use 


/{NO]LOWERCASE /{NO]UPPERCASE 
/WIDTH:n 


Group 2: Terminal Setup 


/VT100 JOA: 
/VT102 7VILOS 
/VT125 JULLS1 
STIL32 /VT200 
/LAS0 /LATS5 
/LA100 /LA210 
/LNO03 /LQPO02 
/PC300 /(NO]TAB 
/{NO]FORM_FEED /{NO]SCOPE 
/{NO]HARDCOPY /PAGE_LENGTH:n 
Group 3: Task Setup 
/{NO]ECHO /(NO]ESCAPE 
/{NO]EIGHT_BIT /{NO]WRAP 


Prompts 
Terminal Attribute? attribute[/attribute[s] ] 


You can set several attributes at once. If one of these commands 
fails, all others following it in the command line also fail. 
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Group 1: Common Use 


The following parameters set terminal characteristics that 
are regularly needed by the average terminal user. 


/{NO]UPPERCASE 


/UPPERCASE is the default. All characters typed on _ the 
terminal appear in uppercase. /NOLOWERCASE is the same as 
/UPPERCASE. 
/ [NO] LOWERCASE 

Characters typed on the terminal in lowercase appear in 
lowercase. Most system tasks will accept input in 
lowercase. Note that some terminal eScape sequences’ use 
lowercase characters. If, for instance, the keypad commands 


in EDT do not seem to be working, you may have to set the 
/LOWERCASE attribute. 


/WIDTH:n 
The SET TERMINAL/WIDTH command sets the width of your 
terminal, that is, the length of a line. The value n can 
range from 0 through 132. Note that a line length of zero 
means no commands can be entered on the terminal. 


Group 2: Terminal Setup 


The following qualifiers set hardware characteristics of 


terminals. For certain common models, you can set a number 
of characteristics automatically simply by identifying the 
model. For other terminals, you must set these 


characteristics explicitly. 


Here are the models for which setup is provided: 


/VT100 #VELOL 

JPVLELVZ /VT105 

/VT125 JVT131 

/VT132 /VT200 

/LA50 /LAT5 

/LA1L00 /LA210 

/LN03 /LOQPO2 

/PC300 /{(NO)]TAB 
/{NO]FORM_FEED /{NO]SCOPE 
/{NO]HARDCOPY /PAGE_LENGTH:n 
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All of these are DIGITAL terminals. Those with "LA" 
designations are hard-copy terminals; those with "VT" and 
"PC" designations are video models. 


Setting a terminal to a particular model does not mean that 
the terminal will behave like that model. It means only 
that the operating system will treat the terminal as if it 
were that model. This feature is intended primarily to 
deceive tasks that expect a certain terminal model or to 
identify a terminal as to what it is. 


You can set hard-copy terminals as video terminals and you 


can set video terminals as hard-copy terminals. For the 
terminal user, the most noticeable difference will be in the 
way the DELETE key operates. Setting terminals from 


hard-copy to video may prove disruptive; setting terminals 
from video to hard-copy is less likely to cause trouble. 


Setting a terminal to a particular’ model designation 
automatically sets a number of attributes for the terminal. 


You can also set these attributes individually. 


You can find out how your terminal is known by issuing a 
SHOW TERMINAL command. 


NOTE 
The DCL single line editor does not honor the ECHO, 
LOWER, WRAP, or WIDTH terminal attributes. 
/NOHARDCOPY 


/ SCOPE 


Sets the terminal as a video terminal. /SCOPE is_- the 
equivalent of /NOHARDCOPY. 


/HARDCOPY 
/NOSCOPE 


Sets the terminal as a hard-copy terminal. /NOSCOPE is’ the 
equivalent of /HARDCOPY. 


/(NO]FORMFEED 
If the terminal hardware supports form feeds, the terminal 
should be set /FORMFEED. If form feeds are handled by the 


software providing line feeds, the terminal should be set 
/NOFORMFEED. 
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/[NO]TAB 


If the terminal hardware supports horizontal tabs, the 
terminal should be set’ TAB. If tabs are handled by the 
software providing spaces, the terminal should be set NOTAB. 


/PAGE_LENGTH:n 


Defines the number of lines to a_ page. By convention, a 
page is usually considered the number of lines to a 
screenful on video terminals or the number of lines’ between 
perforations on hard-copy terminals. This attribute sets 
the length of the page. 


Group 3: Task Setup 


The following parameters set terminal characteristics that 
may be needed by system or user tasks. Most system tasks 
that require these attributes in a terminal will set the 
attributes when they attach the terminal. User tasks can 
also do this. This will be transparent to the user. These 
parameters are included for use in cases where the task does 
not do this setting. 


/{NO]ECHO 


Enables (or disables) echoing of characters typed on _ the 
terminal. 


/ECHO is the default. Characters typed on the terminal are 
echoed on the terminal. 


/NOECHO suppresses the echo. 


/NOECHO changes nothing but echoing. Commands can still be 
passed to the system, but the system passes no echo back. 


/[NO]ESCAPE 


Enables (or disables) recognition of escape sequences from a 
terminal. | 


/NOESCAPE is the default. When you press the ESC key 
(equivalent to CTRL/3 on LK201 keyboards), it is interpreted 
as a line terminator (with a line feed but no carriage 
return). 


ESCAPE enables the recognition of escape sequences from the 
terminal. When you press the ESC key, it is interpreted as 
the beginning of an escape sequence. The ESC key will no 
longer terminate a line. 
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This is a rarely used parameter. Most tasks that recognize 
escape sequences will attach the terminal so that escape 
sequences are passed without the user’s knowledge, usually 
from the keypad. 


/(NO]WRAP 


Specifies that the terminal automatically wrap (or not wrap) 
lines longer than its line width. 


/WRAP is the default. The terminal automatically issues a 
Carriage return and a line feed when you type to whatever 
line width the terminal is set for. 


/NOWRAP overrides this feature and permits unlimited line 
length. 


/{NO]EIGHT BIT 
Enables (or disables) a terminal’s /EIGHT_BIT attribute. 


/EIGHT_BIT is the default, because the Professional 350 uses 
eight bit mode to display the DEC Multinational Character 
Set. /EIGHT_BIT allows the terminal to pass all eight bits 
of the ASCII character. This attribute is used when your 
terminal is communicating with some device that sends 8-bit 
ASL 
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3.72 SHOW ASSIGNMENTS 


SHOW ASSIGNMENTS displays all the logical names in the logical 
name table(s), or it displays the current equivalence value 
assigned to a specific logical name. 
Syntax 

SHOW ASSIGNMENTS[/qualifier[s]] [logical_name] 
qualifier 

Can be any combination of the following: 

/USER 

/SESSION 

/SYSTEM 

/ALL 


logical_name 


Is the name of a unique logical assignment. 


Prompts 

None 
Qualifiers 
/ALL 


Specifies that all logical names in the specified logical 
name table(s) be displayed. 


/USER 
Limits the search to the user logical name table. 

/ SESSION 
Limits the search to the session logical name table. If you 
do not explicitly specify a logical name table, P/OS uses 
/SESSION by default. 


/SYSTEM 


Limits the search to the system logical name table. 
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3.73 SHOW CLOCK_QUEUE 


SHOW CLOCK_QUEUE displays information about tasks that are 
currently in the clock queue. The displayed information 
comprises task names, the next time the task is scheduled to run, 
and each task’s reschedule interval, if any. 
Syntax 

SHOW CLOCK QUEUE 
Prompts 


None 
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3.74 SHOW COMMON 


SHOW COMMON displays the names of resident commons installed in 
the system, their PCB addresses, the number of attached tasks, 
and the status of the common. 


You can also display information about a Single common; 
optionally, you can include a list of tasks attached to the 
common. 


If you do not name a common, information about all commons in the 
Common Block Directory is displayed. 


Syntax 

SHOW COMMON[:name][/qualifier] 
qualifier 

/TASK 
name 

Is the name of the common. 
The display is in the following format: 

commonname pcbaddr taskcount statusbits 

In the format that SHOW COMMON displays at the terminal, 
commonname is the name of the common, pcbaddr is the address of 
the Partition Control Block (PCB), taskcount is the number of 
tasks mapped to the common, and statusbits is a list of common 
region status bits that are set. Usually, the status bits will 


indicate that the common region is either fixed in memory (FXD) 
or out of memory (OUT). 


Table 3-4 lists the status bits and their meanings: 
Prompts 
None 
Qualifier 
/TASK 
Specifies that you want a list of tasks attached to a 


particular common region showing the number of times each 
task is mapped to the common (mapping count). 
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Table 3-4: Status Bits 


Status Bit Meaning 

CAF Checkpoint allocation failure 
-CHK Not checkpointable 

CKP Checkpoint in progress 

CKR Checkpoint requested 

COM Library or common 

DEL Marked for delete on last detach 
DRV Driver common 

FXD Fixed in memory 

LIO Long I/0 

LFR Last load failed 

NSF Not shuffleable 

OUT Out of memory 

PER Parity error 

PIC Position independent 

RON Read-only common 
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3.75 SHOW [DAY]TIME 


This command displays the current day and time. 
Syntax 
SHOW DAYTIME 
or 
SHOW TIME 
Prompts 


None 
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3.76 SHOW DEFAULT 
This command displays the current default device and directory 
name. 
Syntax 
SHOW DEFAULT 
Prompts 


None 
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3.77 SHOW DEVICES 


This command displays information concerning the devices that are 
included in the system. 


Syntax 


SHOW DEVICES[/qualifier] 


qualifier 


Can be one or more of the following: 


Yao | Nh) 
/WIDTH:ddnnn: 


Prompts 


None 


If you do not include a qualifier, SHOW DEVICES displays a list 
of all the devices on the system, including terminals. 


Qualifiers 


/ad[nnn]: 


Displays information about all devices of a particular type 
on the system. The value of dd: is a two-letter device 
mnemonic terminated with a colon, which indicates the type 
of device controller. The display shows the devices under 
that type of controller by model name. 


/WIDTH:ddnnn: 


Displays the size of the I/O buffer (line length) for a 
particular device, including a terminal. 
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3.78 SHOW LOGICALS 


SHOW LOGICALS displays all the current logical names in the 
logical name table(s), or it displays the current equivalence 
value of a specific logical name. 
Syntax 

SHOW LOGICALS[/qualifier[s]] [logical_name] 
qualifier 

Can be any combination of the following: 

/USER 

/SESSION 

/OYSTEM 

YALL 


logical_name 


Is the name of a unique logical assignment. 


Prompts 

None 
Qualifiers 
/ALL 


Specifies that all logical names in the specified logical 
name table(s) be displayed. 


/USER 
Limits the search to the user logical name table. 

/ SESSION 
Limits the search to the session logical name table. If you 
do not explicitly specify a logical name table, P/OS uses 
/SESSION by default. 


/OYSTEM 


Limits the search to the system logical name table. 
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3.79 SHOW MEMORY 


SHOW MEMORY invokes the Resource Monitoring Display (RMD), a 
system utility program. This program displays ina graphic 
manner the status of much of the system. 


The RMD program is useful for monitoring the general activity of 
the system. It is also useful for a new user to see how the 
operating system operates. However, you should understand that 
the graphic display is approximate and cannot be used for 
Critical measurement. (Refer to Chapter 9 for a description of 
RMD. ) 
Syntax 

SHOW MEMORY 
Prompts 


None 
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3.80 SHOW PROTECTION 


SHOW PROTECTION displays the current file protection to _ be 
applied to all new files created during the current session. You 
can change the default protection at any time using the _ SET 
PROTECTION/DEFAULT command. 
Syntax 

SHOW PROTECTION 
Prompts 


None 
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3.81 SHOW TASKS/ACTIVE 
SHOW TASKS/ACTIVE displays information about active tasks in 
brief and full format. 
Syntax (Brief Format) 
SHOW TASKS/ACTIVE[:ttnnn:][{/qualifier[s] ] 
ttnnn: 
If you name a terminal in the command, the display shows in 
brief form the tasks active at that terminal. If you do not 
mame a terminal, the display shows in brief form the tasks 
active at your terminal. 
qualifier[s] 
Can be one or more of the following: 


/BRIEF 
/ALL 


Qualifiers 
/BRIEF 


Specifies that you want to display information about active 
tasks in the brief format. This is the default and need not 


be specified. 


The brief format includes task names and the originating 
terminal in parentheses next to each task name. 


/ALL 
Specifies that you want to display information about all 
tasks active on the system. The default is to show 
information about tasks active at your terminal only. 

Syntax (Full Format) 


SHOW TASKS /ACTIVE/FULL [taskname] 


SHOW TASK[:taskname]/ACTIVE/FULL 
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taskname 


If you include a task name, the display shows Pull 


information on that task. If you do not name a task, the 
display shows full information on all currently active 
tasks. 

Qualifiers 

/FULL 


Requests the full format display for the SHOW TASK/ACTIVE 
command. This format includes detailed information on the 
state of one or all tasks active on the system. The format 
of the display is as follows: 


taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri 

STATUS: statusflags 

TI - ttnnn: IOC - iocount BOC -buffiocount EFLG -eventflg PS -pswval 
PC - pcval REGS 0-6 rival r2val r3val r4val r5val r6oval 


Table 3-5 describes the items that appear in the display. 
If the task is not in memory, the PC, PSW, and other 
registers are not displayed. 


The display shows the state of the task at the time the 
command was issued. You can display similar information 
dynamically (in real time) for a single task with the 
/DYNAMIC qualifier, as explained in Section 3.83. 


Table 3-5: Display for SHOW TASKS/ACTIVE 


Item Description 

tcbaddr The physical address of the Task Control 
Block (TCB). 

parname The name of the task’s partition. 

pcbaddr The physical address of the Partition 
Control Block (PCB). 

taskaddrlimits The base and top of the task’s dynamic 
subpartition as physical addresses. 

pri The priority at which the task is actually 
running. 
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defpri 

STATUS 

TI 

IOC 

BIO 

EFLG 

pswval 

peval 

REGS 

Table 3-6: Task 

Status TCB 

Flag Flag 
ABO T2.ABO 
ACP T3.ACP 
AST TZs2AST 
BLK TS.STP 
CAF T2.CAF 
CAL T3.CAP 
-CHK TS.CHK 
CIP TS.CiP 
CKD TS.CKD 
CKP TS.CKP 
CKR TS.CKR 
CLI T3.CLI 
DST T2.DST 
-~EXE TS.EXE 
FXD T2.FXD 
GFL T3.GFL 
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The default priority at which the task was 
built or installed to run. 

The task’s status flags. These are 
identified in Table 3-6. 

The initiating terminal. 

The decimal I/O count for the task. 

The decimal count of I/0 buffered by the 
terminal driver and Executive. 

Local event flags. 

The Processor Status Word. 

The Program Counter. 

The contents of the task’s other registers. 
If the task was spawned by another task, the 


name of the parent task is also displayed. 


Status Flags 


Meaning 


Being aborted 

Ancillary Control Processor 

AST state 

Blocked externally by CLI command 
Dynamic checkpointing allocation failure 
Checkpoint space allocated in task image 
Not checkpointable 

Blocked for checkpoint in progress 
Checkpointing disabled 

Checkpointed 

Checkpoint request pending 

Command Line Interpreter 

ASTs disabled 

Not executing 

Fixed in memory 

Task has own group global event flags locked 
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Status TCB 

Flag Flag Meaning 

-PMD T3.PMD Suppress PMD on SST abort 

OUT TS.OUT Out of memory 

PRV T3.PRV Privileged 

RDN T3.RDN I/O being run down 

REM T3.REM Remove on exit 

REX T2.REX Abort AST effected or in progress 

ROV T3.ROV Resident overlays 

RST T3.RST Restricted - used by layered software 
SEF T2.SEF Stopped for event flag 

SLV T3.SLV Slaved 

SPN T2.SPN Being suspended 

SPNA T2.SPN Suspended prior to AST 

SEP T2.STP Stopped 

STPA T2.STP Stopped prior to AST 

SWS T3.SWS Reserved for software services 

WFR T2.WFR Ina wait-for state 

WFRA T2.WFR In a wait-for state prior to AST 

DSP T4.DSP Task was built for user-mode I- and D-space 
LDD T4.LDD Task’s load device has been dismounted 
MUT T4.MUT Task is multiuser task 

PRO T4.PRO Task is (or should be) a prototype task 
PRV T4.PRV Task was privileged but has cleared T3.PRV 
SNC T4.SNC Task uses commons for synchronization 


NOTE 


These status flags are displayed by several forms 
of the SHOW TASK command. They give information 
on what is happening within the task and between 
the task and the system. They also identify 


certain kinds of tasks. Names prefixed by a 
minus (-) indicate the complement of the 
condition. Thus, -CHK means the task is 
noncheckpointable. You must understand how the 
system runs tasks to understand the meanings of 
all these flags. See the RSX-11M/M-PLUS and 


Micro/RSX Task Builder Manual and the P/OS System 
Reference Manual for more information. 


32193 


SHOW TASKS/INSTALLED 


3.82 SHOW TASKS/INSTALLED 


SHOW TASKS/INSTALLED displays information about installed tasks 
in either brief or full format. 


Syntax 
SHOW TASKS[:taskname]/INSTALLED[/qualifier[s] ] 
taskname 


Specifies the task for which you want information displayed. 
If you do not specify a task name, information on all 
installed tasks is displayed. 


qualifier[s] 
Can be one or more of the following: 


/BRIEF 
/FULL 


Qualifiers 
/BRIEF 


Requests information on installed tasks ina brief format. 
This is the default and need not be specified. The format 
of the display is as follows: 


taskname ident parname priority size ddnnn:-lbn [memstate] 


In this display, taskname is the name task, ident is’ the 
task version identification (or the version of the prototype 
task), parname is the partition in which the task is 
installed, priority is its priority, size is the size of the 
task in bytes, ddnnn: is the device from which it is to be 
loaded, lbn is the logical block number of its disk address, 
and memstate is the task memory state, which can be FIXED, 
CHECKPOINTED, or blank. 


If the task version identification is missing (with the rest 
of the line moved left) or if it is garbage, the task was 
installed from a disk that is no longer present. If the 
task version number is a date, such as OQ7JUL, the task was 
compiled on that day. 
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taskn 
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Requests the full format of the SHOW TASKS/INSTALLED 
command. This format displays a detailed list of the states 
of one or all of the installed tasks in the system, 
depending on the presence of the taskname parameter. The 
format of the display is as follows: 


taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri 
STATUS: statusflags 
TI - ddn: IOC - iocount EFLG - eventflags 


This display is in the same format as that of 
SHOW TASKS/ACTIVE/FULL. (See Section 3.81 for a description 
of the display.) 

ame 

Specifies a task for which full information is to _ be 


displayed. If you do not specify a task name, information 
about all installed tasks is displayed. 
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3.83 SHOW TASK:taskname/DYNAMIC 


SHOW TASK: taskname/DYNAMIC displays a moving picture of a_ task’s 
activity on the terminal. 


Syntax 

SHOW TASK: taskname/DYNAMIC[/qualifier] 
taskname 

Specifies the task you want to inspect. 
qualifier[s] 

Can be one or more of the following: 


/RATE:n 
/PRIORITY:n 


Qualifiers 
/DYNAMIC 


Specifies that you want the moving display. This function 
is performed by the RMD task. RMD has four display pages: 


e Task that displays a task header 
@ Active that displays all or part of the Active Task List 
@e Memory that displays the contents of memory 


e Help that provides help on RMD 


Once you have invoked any one of these pages, through either 
a SHOW TASK/DYNAMIC command or a SHOW MEMORY command, you 
can move from one page to the other without leaving RMD. 
The first character of each page name is a command to RMD to 
go to that page. In addition, a <CTRL/[> entered from a 
page permits you to enter setup commands for that page. See 
Chapter 9 for more information on the features of RMD. 


The setup commands for the Task page permit you to change 
the task header being displayed. The task you name remains 
the default display for the Task page. This means you can 
observe a single task header, then jump to the Memory page 
or the Active page, and then back to the Task page and_ the 
named task will still be on display. 
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/RATE:n 


The /RATE qualifier allows you to set the rate at which the 
RMD display screen is to be replotted on the first display. 
The value n is the number of seconds between replots. The 
default nis 1. You can change the rate by pressing ESC and 
entering a new rate. The rate setting returns to 1 as_~ soon 
as you change pages. If you want a slower rate, you must 
reset the rate each time you change the page. 


Use this qualifier to slow down the display. 


Task headers may change more often than once per second, but 
once per second is the most rapid rate available. 


/PRIORITY:n 


This qualifier specifies the highest priority to be 
displayed. The default is 250, the highest priority on the 
system. Use this qualifier to shorten the display to. one 
screen length. 


Notes 


Tasks built including ODT can be observed using this 
command, but if you are single-stepping through the task or 
otherwise using breakpoints, the registers displayed will be 
those of the ODT task, not those of the named task. 


This display is particularly useful for observing complex 
assemblies, as you can tell how far the assembly has gone by 
which files are open. You may also be interested in 
observing the Task Builder at work. 
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IW TASKS/ACTIVE/DYNAMIC 


SHOW TASKS/ACTIVE/DYNAMIC displays either a moving picture of the 
Active Task List on a video terminal, or a snapshot display ona 
hard-copy terminal. 


Syntax 
SHOW TASKS/ACTIVE/DYNAMIC[ /qualifier] 

qualifier 
/RATE:n 

Qualifiers 

/RATE:n 
The /RATE qualifier allows you to set the rate at which the 
RMD display screen is to be replotted on the first display. 
The value n is the number of seconds between replots. The 
default mn is 1. You can change the rate once the display 
begins by pressing the ESC key and entering a new rate. The 
rate setting returns to 1 as soon as you change pages. If 


you want a slower rate, you must reset the rate each time 
you change the page. | 


Use this qualifier to slow down the display. 
The Active Task List may change more often than once per 


second, but once per second is the most rapid rate 
available. 
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3.85 SHOW TASK/LOGICAL UNITS 
SHOW TASK: taskname/LOGICAL_UNITS displays the static logical unit 
number (LUN) assignments for an installed task. 
Syntax 
SHOW TASK: taskname/LOGICAL_UNITS 
taskname 


Specifies the task for which you want LUN assignments 


displayed. This must be the name of a task installed 
through INSTALL, and not through the install-run-remove form 
of RUN. 


The display consists of a list of physical devices’ and 
corresponding static LUN assignments. The display does not 
show any dynamic LUN assignments, even when the specified 
task 1S running. 

Prompts 


Taskname? taskname 


3-199 


3.86 SHOW TERMINAL 


SHOW TERMINAL displays information 
another optional terminal 

TERMINAL attribute is directly 
attribute (refer to Set Terminal 
attributes). 

Syntax 


SHOW TERMINAL[:ttnnn: ] 


ttnnn 


Is the number of the terminal for display 


attribute 


Can be one or more of the following: 


Group 1: Common Use 
/ [NO] LOWERCASE 
/WIDTH:n 
Group 2: Terminal Setup 
/VT100 JVTLOL 
/VT102 JVTLOS 
/VT125 /VT131 
/VT132 /VNT200 
/LA50 /LATS 
/LA100 /LA2Z10 
/LNO 3 /LOP02 
/{[NO]FORM_FEED /{[NO]HARDCOPY 
/{NO]SCOPE /{NO]TAB 
/PAGE_LENGTH:n /PC300 
Group 3: Task Setup 

/ [NO ]ECHO 

/{NO]EIGHT_BIT 


connected 


[fattributes[s] ] 


/{NO]UPPERCASE 


/(NO]ESCAPE 
/{NO]WRAP 
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to the system. 


discussion of these 


~-SETS - SET SYMBOL TO STRING VALUE 


The substring select expression is of the form: 


"[start-index:ending-index]". 


~-SETS MYFILE <DIRECT>+"MYFILE.TXT" 


This directive assigns the string symbol MYFILE the string value 
of the current directory and the string contained within the 
quotation marks. For example, if the current directory is 


[USERFILES], then MYFILE is assigned the string value 
[USERFILES ]MYFILE.TXT. 


-SOTOP - TERMINATE COMMAND FILE PROCESSING 
4.46 .STOP - TERMINATE COMMAND FILE PROCESSING 
The .STOP directive immediately terminates command file 
processing and exits. The message 
S$ @ <EOF> 


is then displayed (unless .DISABLE DISPLAY is in effect). 


The .STOP directive allows you to optionally set the exit status 
for Indirect execution. 


Format (brackets not part of syntax) 


-STOP [value] 


where: 
value An optional numeric expression to serve as_ the 
exit status for Indirect. If you do not specify 
an exit status value, the .STOP directive 185 
identical to the logical end-of-file directive 
(7). 
Example 
-o LOR 20 


This directive terminates command file processing and sets’ the 
exit status for Indirect to Q. 


sfEoD = TEST SYMBOL 


4.47 .TEST - TEST SYMBOL 


The .TEST directive has two different functions. It tests a 
variable and sets various special symbols accordingly, and it 
does substring searches and sets the special symbol <STRLEN> 
accordingly. 
Format 1 
-TEST SSSSSS 
where: 
SSSSS The 1- to 6-character symbol to be tested. 
The results of the test are as follows: 
® If variable is a string, <SYMTYP> is set to 4 and 
<STRLEN> contains the length of the string. Also, the 
special symbols <ALPHAN>, <NUMBER>, <RAD50>, and <OCTAL> 
are set based on a scan of the characters of variable. 


e If variable is numeric, <SYMTYP> is set to 2. 


e If variable is octal, <SYMTYP> is set to 2 and <OCTAL> 
is set to TRUE. 


e If variable is logical, <SYMTYP> is set to Q. 
Format 2 
.TEST string substring 
where: 
string A string symbol or constant. 
substring A string expression. 
In this case, the substring is searched for in the _ specified 
string. If the substring is present, <STRLEN> is set to the 


position of the starting character of the substring within the 
string. If substring is not present, <STRLEN> is set to Q. 


-TEST - TEST SYMBOL 


Examples 
1. If SUM is a string symbol, the directive statement: 
-TEST SUM 


sets <SYMTYP> to 4 and places the number of characters 
represented by the symbol SUM into <STRLEN>. 


2. The directive statements: 


-SETS MAIN "ABCDEF" 
.TEST MAIN "C" 


set <STRLEN> to 3, C’sS position in string ABCDEF. 


~TESTDEVICE - TEST DEVICE 


4.48 .TESTDEVICE - TEST DEVICE 


The .TESTDEVICE directive allows a command file to acquire 
information about any device in the system. The information, 
including error indications, is contained in the string symbol 


<EXSTRI>. Each device attribute in the string is separated by a 
comma (which allows processing by the . PARSE and eTEST 
directives). The first field of the string is the full physical 
name of the device. The next four fields are octal 
representations of the device-characteristics words (U.CW1 
through U.CW4 of the Unit Control Block). Additional fields 


contain more information about the device. 
Format 

.TESTDEVICE dd[nn]: 
where: 


dd[nn]: The device about which the command file is 
requesting information. 


The information stored in <EXSTRI> is in the following form: 


ddnn:,xXx,XX,Xx,xx,atr,atr...,atr, 


where: 
ddnn: The physical device name for the device specified 
in the command line. 
KX pK; The four device-characteristics words in octal 
eK, KX notation. 
atr One or more of the following device attributes: 
NSD "No such device" is configured into this 
system. 
LOD The device driver is loaded. 
UNL The device driver is not loaded. 
Example 


-TESTDEVICE SY: 


This directive acquires information about user logical device SY: 
and stores it in <EXSTRI>. 


-TESTFILE - TEST A FILE 
4.49 .TESTFILE - TEST A FILE 


The .TESTFILE directive determines if a specified file exists. 
If you specify a file in the command line, the results of a 
.TESTFILE operation are contained in the symbols <FILSPC> and 
<FILERR>. <FILSPC> contains the fully qualified File 
specification and <FILERR> contains the FCS status code resulting 
from the search for the file. 
Formats 

-TESTFILE filespec 
where: 

filespec Is the file to be tested. 

Examples 

-TESTFILE IND.MAP 


This directive assigns the following values if the file exists: 


il 
DW1:[USERFILES]IND.MAP;4 


<FILERR> 
<FILOPC> 


If the file does not exist, the directive assigns the following 
values: 


<FILERR> = 230. 
<FILSPC> = DW1:[USERFILES]IND.MAP;0 


The following directive translates the logical name TI: into its 
physical device name. 


«TEST FILE Tl: 
The directive assigns the symbol values as follows: 


1 
TT1: .DAT;0 


<FILERR> 
<FILSPC> 


-~TESTPARTITION - TEST A PARTITION 


4.50 .TESTPARTITION - TEST A PARTITION 


The .TESTPARTITION directive allows a command file to obtain 
information about a partition in the system. The partition can 
be the one in which Indirect is running or any other partition. 
You can use the directive to verify that a partition is large 
enough before installing a task in it or that the partition is 
present before loading a special system. Indirect returns the 
information (in the special symbol <EXSTRI>) in the following 
format: 


partition-name,base,size,type, 
where base and size are in 64-byte blocks and type is SYS _ for 
system-controlled partitions, USR for user-controlled partitions, 
or NSP for an unknown partition name. If the partition is not 
found, Indirect returns a "No Such Partition" error in the form: 
partition-name,,,NSP, 
Format 
-TESTPARTITION partition-name 


where: 


partition- A 1- to 6-character legal partition name. 
name 


Example 


.TESTPARTITION GEN 
7;GEN,1500,2303,SYS, 


This directive obtains information about the partition named GEN. 
The partition has a starting address of 150000 (octal), is 230300 
(octal) bytes long, and is a system-controlled partition. 


~TESTSYSTEM - TEST SYSTEM 


4.51 .TESTSYSTEM - TEST SYSTEM 


The .TESTSYSTEM directive allows a command file to acquire 
information about the presence of certain operating system 
features. 


Format 
-TESTSYSTEM keyword number 
where: 


keyword identifies the system component to be returned. 
Valid keywords are: 


OPTION which interprets the immediately 
following symbol (number) as a number 
indicating the system feature to be 
interrogated. 


SERIAL which returns’ the processor serial 
number in the <EXSTRI> return string 
value. 


number is a number representing the desired feature. 
(Symbolic equivalents for these numbers, called 
system feature symbols, are listed in the P/OS 
System Reference Manual under the description of 
the FEATS system directive.) For convenience, 
the command library INDSYS.CLB contains a 
procedure (INDSFN) that performs feature 
testing. The return value of string <EXSTRI> is 
the string "<TRUE>" or "<FALSE>", depending upon 
whether or not the current system contains or 
was built with the indicated feature. 


Example 


@DW1:[1,2]INDSYS/LB:INDSFN HFSFPP ! is FPP present? 
-SETL FPUPRS '’<EXSTRI>’ 


Sets the logical symbol FPUPRS to true or false, depending on 
whether or not the floating point chip is installed on this 
system. HFSFPP is a system feature symbol. 


-TESTSYSTEM OPTION -16. 
-SOETL FPUPRS '’<EXSTRI>’ 


-TESTSYSTEM - TEST SYSTEM 


Does the same as the previous example, except that it uses_ the 
actual number representing the FPP (-16.) rather than the system 
feature symbol (HFSFPP). 
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4.52 .TRANSLATE - TRANSLATE A LOGICAL NAME 


This directive attempts to translate a logical name as defined by 
the DCL command ASSIGN. 


Format 

»~TRANSLATE logical-name 
If available, the translated value of ’logical-name’ is’ returned 
in <EXSTRI>. The logical-name must have been previously defined 
(using the ASSIGN command, for example). 
The .TRANSLATE command will translate a logical name by first 
searching in the USER logical name table. If the logical name is 
not found, the SESSION logical name table is’ searched. If the 
logical is still not found the SYSTEM table is searched. 

NOTE 


You cannot limit the search to a particular table 
as you can in DCL. 


Example 


The directive: 


-TRANSLATE LDWOO1: 
;'’<EXSTRI>D’ 


displays the following: 


;BIGDISK 


-WAIT - WAIT FOR A TASK TO FINISH EXECUTION 


4.53 .WAIT - WAIT FOR A TASK TO FINISH EXECUTION 


.WAIT is provided for compatibility with command files moved from 
RSX-11 systems. It is a no-op under the PRO/Tool Kit. 


-XQOT - INITIATE PARALLEL TASK EXECUTION 


4.54 .XQT - INITIATE PARALLEL TASK EXECUTION 


-XQT is provided for compatibility with command files transferred 
from RSX-11 systems. The remainder of the command line is passed 
to DCL as though the ".XQT" had not been present. 


COMPATIBILITY WITH COMMAND FILES FROM RSX SYSTEMS 


4.55 COMPATIBILITY WITH COMMAND FILES FROM RSX SYSTEMS 


Many features of the indirect command processors present on 
RSX-11M and RSX-11M-PLUS has been preserved under the PRO/Tool 
Kit. Because of differences in the goals of the P/OS_ system, 
some commands and symbols have little or no meaning. For 
example: 


e The .WAIT and .XQT commands are present and parsed but behave 
as no-operation commands. 


e The .XQT command is implemented as a synchronous’ operation, 
Since it is not possible to initiate multiple commands or 
programs for parallel execution. 


e The .PAUSE command does not pause. Command file processing 
continues without delay. 


The following special symbols are available in the symbol table 
of the PRO/Tool Kit INDIRECT. When transporting procedures from 
other RSX-11 systems that make use of these symbols, examine such 
usage and make any appropriate changes. 


<ALTMOD> use <ESCAPE> 

<BASLIN> always <FALSE> 

<CONFIG> see module INDCFG in the procedure 

<ERRCTL> 'behave as on RSX-11 systems 

<ERRNUM> behave as on RSX-11 systems 

<ERRSEV> behave as on RSX-11 systems 

<FILATR> as on RSX-11 systems 

<FMASK> see module INDSFN 
in library LB000:[({1,2]INDSYS.CLB. 

<IAS> always <FALSE> 

<LIBUIC> not meaningful 

<LOCAL> always <TRUE> 

<MAPPED> always <TRUE> 

<NETUIC> not meaningful 

<NXTSYM> use module INDDMP in LB000:[{1,2]INDSYS.CLB 

<RSX11D> Always false in RSX-11M/M-PLUS and P/OS 
systems 

<SYSUIC> not meaningful 

<TISPED> always 0 on TT1: 
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4.56 INDIRECT MESSAGES 


When Indirect encounters an error, it prints the appropriate 
error message and the command line in which the error occurred. 


If the line contained a substitution, the line as it 
before the substitution took place is also displayed. 


4.56.1 Information-Only Messages 
@ <EOF> 
Indirect has reached the end-of-file for the 


command file and is terminating execution. 


IND -- CONTINUING 


appeared 


outermost 


Indirect is resuming execution after a .PAUSE or .DELAY 


directive. 


IND -- DELAYING 


A .DELAY directive was just executed, halting the 
processing of an indirect command file for a specified 


period of time. 


IND -- INVALID ANSWER OR TERMINATOR 


In response to a question from .ASK, you 


entered 


something other than Y, N, or null, followed by a 


RETURN; or you did not enter a numeric 


value in 


response to an .ASKN question; or you pressed the 


<ESCAPE> key either without escape recognition 


enabled 


or aS a character other than the first one following 


the question. The question will be repeated. 
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IND -- VALUE NOT IN RANGE 
The response to an .ASKN or .ASKS question was not 


within the specified range. Indirect repeats’ the 
question. 


4.56.2 Error Messages 
IND -- BAD RANGE OR DEFAULT SPECIFICATION 
An illegal character was specified as a range or 


default argument. Only numeric expressions are 
permitted. 


IND -- COMMAND FILE OPEN ERROR 


The file being invoked in an @file or @file/LB:module 
command line cannot be found or opened. 

IND -- DATA FILE ERROR, CODE x. 
Indirect encountered an error while processing an 
.OPEN, .OPENA, .CLOSE, or  .DATA directive or a data 
mode access to the secondary file. 

IND -- FILE ALREADY OPEN 
An .OPEN or .OPENA directive specified a file that was 
already open. 

IND -- FILE NOT FOUND 
An @filename or .CHAIN directive specified an incorrect 
file name or nonexistent file. 

IND -- FILE NOT OPEN 


Indirect encountered a .DATA or .CLOSE directive that 
did not reference an open file. 
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FILE READ ERROR 

An error was detected in reading the indirect command 
file. This error is usually caused by records that are 
more than 132 (decimal) bytes long. 

ILLEGAL FILE NUMBER 

The file number in an .OPEN, -OPENA, ~OPENR, .DATA, 
-ENABLE DATA, .READ, or .CLOSE directive is not in the 
range of Q through 3. 

ILLEGAL NESTING 

Too many Begin-End blocks have been nested in the 
indirect command file. The maximum nesting depth is 
limited to the size of the symbol table. 

INITIALIZATION ERROR, CODE x. 

Indirect failed to complete initialization when you 
invoked it. The following list gives the meaning of 


the displayed code number: 


1. Unable to acquire system information such as 
the UIC or device name. 


2. Impure area setup failed. 
3. Unable to acquire task-specific information. 
4. Unable to acquire terminal-type information. 


5. Unable to acquire the disk name and other 
information about the system device (SY:). 


6. Unable to allocate enough space for command 
and data I/O buffers. The EXTEND TASK 
directive failed to return sufficient space 
for Indirect to allocate the buffers. 


7. Initialization of allocated buffers failed. 


8. Initialization of the DATA file structures 
failed. 


9. Allocation of FCS-11 buffers for data and 
command lines failed. 
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10. Symbol table initialization failed. 
11. Initialization cleanup failed. 
12. Unable to obtain initial command line. 


13. Unable to initialize the FMS-11 forms driver 
impure area. 


>13. Error codes greater than 13 are returned by 


Special purpose initialization modules. 


Error number 6 is the only initialization error’ that 
you should encounter. If any other error from 1 
through 12 persists, call your DIGITAL Customer Support 
Center. 

INVALID KEYWORD 

An unrecognized keyword (preceded by a period) was 
specified. 

LABEL NOT AT BEGINNING OF LINE 

The specified label does not start in the first column 
of the line. All labels must do so. 

MAXIMUM INDIRECT FILE DEPTH EXCEEDED 

An attempt was made to reference an indirect command 
file at a nested depth greater than the maximum 
specified in the build file for the Indirect task. 

NO POOL SPACE 

The executive dynamic memory allocation has been 
exhausted. 

NULL CONTROL STRING 

The control string specified with the .PARSE directive 


was null (there were no characters between the 
quotation marks). 


IND 


IND 


IND 


IND 


IND 


IND 


IND 
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NUMERIC UNDER- OR OVERFLOW 


The evaluation of a numeric expression yielded a value 
outside the range 0 through 177777 (octal). 


REDEFINING A READ-ONLY SYMBOL 


An attempt was made to assign a new value to a 
read-only symbol. Read-only symbols cannot’ be 
overwritten. 


REDEFINING SYMBOL TO DIFFERENT TYPE ssssss 


An .ASK, .ASKN, -ASKS, -READ, ioe cel ted Aer SOE TE, so ELiy 
-SETN, or .SETS directive was used in an attempt to set 
the specified, already defined symbol to a different 
type. The first definition of a symbol determines its 
type (logical, numeric, or string); subsequent value 
assignments must conform to the original type. 


-RETURN WITHOUT .GOSUB 

A .RETURN directive was specified without a previous 
call to a subroutine (.GOSUB). 

STRING EXPRESSION LARGER THAN 132. BYTES 

An attempt was made to generate a string expression 
longer than 132 (decimal) characters. 

STRING SUBSTITUTION ERROR 

Indirect encountered an error during a_e substitution 
operation. A probable cause for the error is either 
the omission of a second apostrophe or the 
specification of a symbol that is not defined. 
SUBROUTINE NESTING TOO DEEP 

The maximum subroutine nesting level was exceeded. The 


maximum level is specified in the build file for the 
Indirect task. 
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SYMBOL TABLE OVERFLOW sSSSSS 

The symbol table was full and there was no space _ for 
symbol ssssss. 

SYMBOL TYPE ERROR SSSSSS 

The symbol ssssss was used out of context for its type; 


for example, a numeric expression referenced a logical 
symbol. Only symbols of the same type can be compared. 


SYNTAX ERROR 


The format of the specified command line is incorrect. 


UNDEFINED LABEL .label: 

The label .label: specified in a .GOTO, .GOSUB, or 
-ONERR directive could not be found. 

UNDEFINED SYMBOL SSSSSS 


The symbol ssssss was referenced, but it had not been 
defined. 
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CHAPTER 5 
CUSTOMIZING PRO/DCL 


PRO/DCL offers a number of features for customizing the command 
interface. This chapter describes how to: 


@e Customize command processing with the Catchall facility 
@e Change the default editor used with the EDIT command 


@e Disable the EXIT command 


This chapter also presents: 
@e The logical names that are created in PRO/DCL 


e The location of startup, exit, and application command 
files that you can modify 


@ The way the automatic flying install feature lets you 
run a task that was not previously installed 


5.1 THE CATCHALL FACILITY 


This section describes the PRO/DCL Catchall facility, explains 
how to use it to customize command processing by defining the 
logical name DCLSCOMMAND_OPTIONS, and finally provides guidelines 
for writing a catchall task, which can expand or modify the 
PRO/DCL command set. 


5.1.1 An Overview 


The Catchall facility is a PRO/DCL feature that allows you to 
customize PRO/DCL command processing. You can specify one or 
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more modes of command processing and the order in which they 
Should occur. PRO/DCL processes commands by passing commands to 
tasks or by checking command tables to determine the validity of 
an entered command. | 


PRO/DCL allows you to process commands in one or more of the 
following ways: 


@ Execute a subset of DIGITAL Command Language (DCL) 
commands. Chapter 3 describes PRO/DCL commands. 


@e Execute a subset of Monitor Console Routine (MCR) 
commands. Appendix D describes PRO/MCR commands. 


@® Install, run, and remove a task. 
@e Run a user-written task. 


e Run the system-supplied TDX catchall task. (TDX is a 
sample catchall task that DIGITAL Corporation provides 
as a model for writing a catchall task. The TDX task 
defines a number of commands that call P/OS services 
directly without exiting the PRO/DCL environment.) 


The following section explains how to use the Catchall facility 
to specify the appropriate mode of command processing. After you 
read this section, you can write a catchall task if either’ the 
PRO/Tool Kit or the Host Tool Kit is installed on your system. 
Read Section 5.1.5 for guidelines on writing this type of task. 


5.1.2 Using the Catchall Facility 


To use the Catchall facility, you must define the logical name 
DCLSCOMMAND_OPTIONS and equate it to a list of one or more 
values, called a control list. Each value in the control list 
specifies a command processing mode, as listed above. When you 
enter a command in PRO/DCL, the PRO/DCL task interprets’ the 
values in the control list one at a time, from left to right. 
PRO/DCL attempts to process the command using the method 
specified by each value in the control list until one of the 
following occurs: 


@e The command has been successfully processed. 


e® A fatal error has occurred. 
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@® There are no more values in the list to interpret. 


If the logical name DCLSCOMMAND_OPTIONS does not exist, PRO/DCL 
interprets all commands entered as DCL commands. Once you have 
defined this logical, the mode of command processing you have 
specified applies both to commands entered interactively and to 
commands in indirect command files. 


5.1.3 Logical Name DCLSCOMMAND_ OPTIONS Format 


DEFINE DCLSCOMMAND_OPTIONS (keyword,keyword,...,tsknam) 
keyword 


Can be one or more of the following: 


DCL 
Specifies DCL command processing. PRO/DCL searches a 
table of valid DCL commands for the command that has 
been entered. If the command is found, PRO/DCL passes 
it to the appropriate utility for processing. If the 
command is not found, PRO/DCL checks the next value in 
the control list, if there is one. If there are no 
more values in the control list, PRO/DCL displays an 
error message. 

MCR 


Specifies MCR command processing. PRO/DCL attempts to 
process MCR commands in two ways. First, it searches a 
table of valid MCR commands for the command verb that 
has been entered. (Note that MCR recognizes only the 
first three characters of a command verb, and _ the 
command verb must be at least three characters long to 
be a valid MCR command.) If the command is_ found, 
PRO/DCL passes it to the appropriate utility for 
processing. 


IRR 
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Second, if the command is not found, PRO/DCL searches 
the System Task Directory (STD) for an installed task 
with the first three characters of the command verb 
that was entered. That is, it searches for a task name 
in each of these forms: 


XX¥xXTnNN OT ..26-eXXX 


where xxx represents the first three characters of the 
command verb, and Tnn represents the number of the 
terminal from which the command was issued. 


If an installed task is found, PRO/DCL calls the task, 
passing the command line to it. If the command verb is 
neither a valid MCR command nor a currently installed 
task, PRO/DCL checks the next value in the control 
list, if there is one. If there are no more values in 
the control list, PRO/DCL displays an error message. 


Specifies that PRO/DCL should attempt to install, run, 
then remove a task image. PRO/DCL generates a RUN 
command in the following format: 

RUN $xxx/TASK=Tnn/COMMAND="params..." 


xx Specifies the command verb 


nn Specifies the number of the terminal 
from which the command was issued 


params Specifies the first three characters 
of the verb, followed by a space, and 
the rest of the command line received 
by PRO/DCL 


For example, if IRR is the current value in the control 
list, and you enter the command line: 


CVT 12.+14. 


PRO/DCL will attempt to install, run, then remove the 
task SCVT, passing the command line: 


CVT 12.+14. 


to the task. If the task image is not found in 
LB:[ZZPRODCL], then the next value in the control list 
is interpreted. If there are no more values in the 


control list, PRO/DCL issues an error message. 
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tsknam 


Specifies the name of an installed catchall 


PRO/DCL encounters a value in the control list that is not 


one of the predefined keywords (DCL, MCR, 


considers the task name an installed catchall task. 


PRO/DCL searches the System Task Directory for an 
task that has the task name in the control list. 
is of the form xxx, PRO/DCL searches for a task in 


these forms: 


XX¥XTnnN Or .«eXXX 


task. When 
or IRR), it 
installed 

If Tsknam 
each of 


where xxx represents Tsknam, and Tnn represents the terminal 


from which it was issued. 


If an installed task is found, PRO/DCL 


passing it the command line that was entered. 


5.1.4 The TDX Catchall Task 


DIGITAL has provided a sample catchall task, called MTDxX, 


the task, 


defines a number of commands that call P/OS services, 


eliminating the need for you to exit the PRO/DCL 


You can use the TDX task in two ways: 


which 


thus 


environment. 


@e Install it and execute any of the commands’ that 


defines. 


it 


® Use it as a model for creating your own catchall task. 


NOTE 


The TDX catchall task is a sample catchall 


created by DIGITAL for P/OS Version 3.2. 
reserves the right to change system 


task 


DIGITAL 
component 


file names. DIGITAL cannot guarantee that the 


commands defined in the TDX task will work 
future versions of either P/OS or PRO/DCL. 


with 
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5.1.4.1 Installing the TDX Task 
To install the TDX task, follow these steps: 


1. Insert the diskette labelled "PRO/DCL Help 2." 

2. Type the following commands: 
COPY DCLHLP2:[TDX]TDX.TSK outputfile 
The outputfile is the name and location in which you 
want to place the catchall task. If all system users 
are to use the catchall task, the system manager or a 


privileged user should copy the task to LB:[ZZPRODCL]. 


INSTALL outputfile /TASK=...TDX 


5.1.4.2 Using the TDX Task 

After you have installed the TDX task, define the logical name 
DCLSCOMMAND_OPTIONS and equate it to one or more of the values, 
DCL, MCR, IRR, or tsknam. For example: 

DEFINE DCLS$COMMAND OPTIONS (DCL,TDX) 


This command specifies that all commands be processed as_ DCL 


commands first. Then, if they are not recognized as valid DCL 
commands, PRO/DCL searches the System Task Directory for an 
installed task named ...TDX. If it is found, PRO/DCL calls the 


TDX task, passing the command line to the task. 


If TDX does not understand the command, it attempts to install, 
run, then remove LB:[ZZPRODCL]commandname from the System Task 
Directory. If that fails, PRO/DCL attempts to install, run, then 
remove LB:(ZZSYS]commandname from the System Task Directory. If 
these attempts fail, it interprets the next value in the control 
list, if there 1s. one. If there are no more values in the 
control list, an error message is displayed. 
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5.1.4.3 Getting Help with TDX Commands 


To see a list of the TDX commands, make sure that logical name 
DCLSCOMMAND_OPTIONS is equated to (DCL,TDX). Then enter the 
following command: 


TDX HELP 


5.1.5 Guidelines on Writing a Catchall Task 


In order to write a user-defined task, you need either’ the 
PRO/Tool Kit or Host Tool Kit. Before you write a catchall task, 
print out and review the source file for the TDX catchall task 
that DIGITAL supplies. The routines in this sample task show the 
procedures needed for a catchall task to operate properly in the 
PRO/DCL environment. 


You should write a catchall task using the following coding 
conventions: 


@® Exit with consistent exit status values that are 
appropriate to the way the command was processed. 


@ Include a routine that aborts the catchall task when a 
user enters <CTRL/C>. 
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5.1.5.1 Passing Exit Status Values 


To provide left-to-right processing of the values in the control 
list, each invoked catchall task should exit with a status that 
1S appropriate to the disposition of the command. Table 5-1 
lists the exit status values that a catchall task should return 
and explains the meaning of each value. 


Table 5-1: Catchall Task Exit Status Values 


Exit Status Meaning 


EXSSUC The command was processed 
successfully. PRO/DCL will then 
prompt for the next command or 
retrieve the next command from 


the Indirect Command File 
processor. 
EXSWAR The command is unrecognized by 


the catchall task. No warning 
or error message was displayed 
to the user. This exit status 
value is used to pass the 
command line to the next 
process in the control list. 


EXSERR or EXSSEV Indicates that an error 
occurred or the command line 
was not recognized. If one of 
these exit values 1s. used, 
PRO/DCL will assume that a 
message was displayed to the 
user and will then prompt for 
another command. 


5.1.5.2 Aborting the Task 


In addition to passing appropriate exit status values, catchall 
tasks should be able to process abort attempts. If a user types 
<CTRL/C> at the terminal, PRO/DCL aborts the current active 
process or catchall task. When the user makes an abort attempt, 
the catchall task should close any open files, then exit. 
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The catchall task can respond to <CTRL/C> either by attaching the 
terminal for <CTRL/C> notification or by using the TC.CLC 
Characteristic in the SF.SMC function. Chapter 11 in the P/OS 
System Reference Manual describes CTRL/C trapping. 


5.1.6 Changing the Control List 


As stated earlier, the Catchall facility offers several different 
ways to process commands in PRO/DCL. But the real power of the 
Catchall facility comes from the way you arrange keyword values 
in the control list. 


This section presents a few examples of how changing the order of 
keywords in the control list affects command processing in 
PRO/DCL. 


For instance, you can use the control list to exit from a task to 


the DCL prompt. This procedure allows you to get around that 
fact that you cannot write a catchall task that can exit from 
PRO/DCL. If you write a catchall task called CAT and enter this 
command: | 


DEFINE DCLSCOMMAND OPTIONS (CAT) 


you lock yourself out of PRO/DCL. When you type a termination 
command, PRO/DCL passes the command to the only keyword in the 
control list, CAT. CAT cannot exit PRO/DCL. To avoid this 
Situation, enter the command: 


DEFINE DCLSCOMMAND OPTIONS (CAT,DCL) 


Now the CAT task can exit with EXSWAR status, which tells PRO/DCL 
to pass the terminating command to the next keyword in the 
control list, DCL. 


Another example of using the control list to customize DCL is 
selectively disabling one oor more commands. For example, on a 
multiuser system, you could write a catchall task called TURNKEY, 
which tests the terminal id from which commands are entered. 
Define the logical name DCLSCOMMAND_OPTIONS as follows: 


DEFINE DCLS$SCOMMAND_OPTIONS (TURNKEY,DCL) 
If the TURNKEY task exits with status EXSWAR, the command is 
passed to the next keyword in the control list, DCL. If the 


TURNKEY task exits with status EXSERR or EXSSEV, PRO/DCL assumes 
that the command was not recognized and prompts for the next 


aa, 
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command. This technique could be used to _ selectively disable 
EXIT commands on a multiuser system. 


5.2 CHANGING THE DEFAULT EDITOR 


The default editor that PRO/DCL calls when you execute the EDIT 
command is PROSE. PRO/DCL determines which editor to invoke as 
the default editor by translating the logical name DCLSEDITOR. 
In PRO/Tool Kit, this logical has been defined as EDT. In 
Command Language, the logical has not been defined, and 
therefore, the default editor remains PROSE. 


You can change the default editor that PRO/DCL invokes’ by 
defining the logical name DCLSEDITOR and equating it to the value 
EDT, PROSE, SLP, or the name of an installed task. Thus, you can 
specify the task of an editor you prefer to use as the default 
editor. 


If you specify the name of an installed task, you can only 
specify three characters in the form xxx. Therefore, the editor 
task should be installed as xxx or ...xxx. The ...xxx form 18s 
recommended. 


Example: 
$ DEFINE DCLSEDITOR FOO 
S$ INSTALL EDITOR.TSK/TASK=...FOO 


S EDIT ! The editor installed as ...FOO is invoked with any 
! command parameters entered with the EDIT verb. 


Regardless of the current default editor, you can invoke PROSE, 
EDT, or SLP by specifying it as the qualifier to the EDIT 
command. For example, EDIT/EDT always calls the EDT editor. 
EDIT/PROSE always calls the PROSE editor, and EDIT/SLP always 
calls SLP (the Source Language Input Program). 


DISABLING THE DCL EXIT COMMAND 


5.3 DISABLING THE DCL EXIT COMMAND 


You can disable the EXIT command by defining the logical name 
DCLSDISABLESEXIT and equating it to the first character of the 
terminal name and the unit number of the terminal. For example, 
to disable the EXIT command while running PRO/DCL on TT1: type: 


DEFINE DCLSDISABLESEXIT T1 


If the EXIT command is entered, DCL will display the error 
"Tllegal command." 


If the PRO/DCL application is running on multiple terminals 
Simultaneously, you can disable DCL from exiting on some or all 
terminals. To do this, create the logical name DCLSDISABLESEXIT 
in the SYSTEM logical name table and equate it to the terminals 
on which you want the EXIT command to be disabled. The 
equivalence name is created in the form Tn,Tn... 


For example, the following command line disables the EXIT command 
on any DCL application (either Command Language or the PRO/Tool 
Kit) executing on terminals TT1: and TT3: (SLU Port Q): 


DEFINE/SYSTEM Ti, T3 


5.4 LOGICAL NAMES 


When you invoke PRO/DCL, the logical names shown in Table 5-2 are 
created. 


LOGICAL NAMES 


Table 5-2: Logical Names for PRO/Tool Kit 


Logical Name Equivalence Purpose 
APPLSDIR: LBO000: [ZZPRODCL ] Points to the library 
APPLSDIR device and the directory 


that contain all PRO/DCL 
application task images. 
This directory contains 
the per-system startup 
and exit command files. 
It is also the string to 
which the ’S’ character 
resolves in the RUN and 
INSTALL commands. You 
can use this logical 
name in file 


Specifications. 
DCLAPPLSDIR: File spec Points to the device and 
DCLAPPLSDIR directory where the 


PRO/DCL application 
files reside. This 
directory contains the 
per-user startup and 
exit command files. 


DCLSEDITOR EDT, PROSE,SLP Defines the default 
(user-defined) editor. Equivalence 

values can be EDT, 
PROSE, SLP, or the name 
of an installed task of 
any other editor. If 
this logical does not 
exist, your default 
editor becomes PROSE 
(the Professional 
editor). 


DCLSCOMMAND_OPTIONS (Keyword[,...]) Defines the current mode 
of PRO/DCL command 
processing. Equivalence 
values can be DCL, MCR, 
IRR, or tsknam. 


LOGICAL NAMES 


Logical Name Equivalence Purpose 


INDSCOMMAND_LIBRARY File spec Points to the device and 
directory that contain 
user-written command 
files. If a command file 
is not found in the 
current default device 
and directory, the 
PRO/DCL indirect command 
processor will attempt 
to translate the logical 
name INDSCOMMAND_LIBRARY 
and look for the command 
file there. Note that 
PRO/DCL uses LB:[1,2] as 
the initial value of the 
logical name 
INDSCOMMAND_ LIBRARY. You 
can specify your own 
initial value in the 
file START.CMD. 


5.5 START AND EXIT COMMAND FILES 


When the PRO/Tool Kit is invoked, two startup command files are 
processed. The first, LBO000:[ZZPRODCL]START.CMD, 1S a system 
startup file. Once this command file completes execution, 
DCLAPPLSDIR:START.CMD, a user-specific startup command file, is 
processed. 


Similarly, when you exit the PRO/Tool Kit application two exit 
command files are processed. The first exit command file to be 
processed is LB000:[ZZPRODCL]EXIT.CMD, which is a system exit 
command file. Then the user-specific command file, 
DCLAPPLSDIR:EXIT.CMD, is processed. 


5.6 MODIFYING APPLICATION INSTALLATION FILES 


By default, the application installation files provided with the 
Command Language and PRO/Tool Kit install all tasks needed to 
perform the commands that are allowed in the application. You 
can modify the INB files, using your favorite editor, to delete 
lines that install components that you do not normally use. This 
will speed application startup and save system resources. Fora 
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list of the tasks or utilites that perform DCL commands, refer to 
Appendix A. 


5.7 FLYING INSTALLS 


Flying install is the process by which PRO/DCL installs, runs, 
then removes a task or utility that is needed to process a 
particular PRO/DCL command, if the task is not currently 
installed in the System Task Directory (STD). If the task needed 
to perform a command is not installed in the STD or found on the 
system disk, the error message "INS -- File not found" 1s 
displayed. 


The language commands, such as FORTRAN, PASCAL, BASIC, COBOL, 
will not perform flying installs. Also, EDIT/PROSE will not 
install the callable editor task CET. 


CHAPTER 6 
FILE COMPARE UTILITY (CMP) 


The File Compare Utility (CMP) compares the contents of two ASCII 
files on a line-by-line basis, determining whether parallel 
records are identical. The utility produces a listing of the 
differences between the two files. 


Using CMP, you can perform the following file-compare functions: 


@e Generate a listing showing the differences between the two 


files. Each difference is listed as a pair: first, the 
lines from the first file, then the lines from the second 
file. 


@ Generate a listing in the form of one list, with differences 
marked by change bars. 


@ Generate output suitable for input to the Source Language 
Input Program utility (SLP). This output contains the SLP 
commands and input required to make the first input file 
identical to the second input file. (For more information on 
SLP, see Chapter 11.) 


CMP provides switches that allow you _ to control compare 
processing. Using these switches, you can control the comparison 
of blanks, tabs, form feeds, and comments. You can also’ control 
line numbering and specify the number of lines required for CMP 
to consider that a match has been made between lines in the _ two 
files. 


INVOKING CMP 


6.1 INVOKING CMP 


You can invoke CMP in two ways: 


1. Invoke the DIFFERENCES command, which in turn invokes’ CMP. 
see Chapter 3 for a description of the DIFFERENCES command. 


2. Invoke CMP directly from the DCL command level. 
To invoke CMP directly from the DCL command level, enter’ the 
following command: 

S$ RUN SCMP 


You receive a new prompt to indicate that you are in the CMP 
environment: 


CMP> 


Once you are in the CMP environment, CMP waits for your command. 
The following section describes the command format. 


6.2 CMP COMMAND FORMAT 
The format for a CMP command is: 
f[outfile[{/sw...]J=] infilel,infile2 
outfile 
The file specification for the output file. This file can 


be in one of three formats, depending on the switch you 
specify in the command line. The defaults are: 


SY0: User’s default system device 

[curdir] Current directory CMP is running under 
FILCOM Default file name 

. LST Default file type 


However, if you do not specify an output file, the output 
defaults to your terminal screen. For example: 


CMP>FILE1.MAC, FILE2.MAC 


CMP COMMAND FORMAT 


CMP lists the differences between FILE1.MAC and FILE2.MAC on 
your terminal screen. If you type the equal sign but give 
no output file specification, only the total number of 
differences is output to your terminal screen. For example: 


CMP>=FILE1.MAC;1,FILE2.MAC;1 
10 differences found 


[SWeee 


Switches that you apply to the output file specification. 
Some of the switches can be negated and some are mutually 
exclusive. See Section 6.3 for more information. 


infilel 


The file specification for the input file to be compared to 
infile2. The file name of this file must be specified. The 
default file type is .MAC. 


infile2 


The file specification for the input file to be compared to 
infilel. You do not have to have a complete file 
specification. The specifications for infilel are used as 
defaults for any unspecified portions of infile2. For 
example: 


CMP>DZ1: [FOO]EXEC, ;2 
CMP interprets the second input file as DZ1:[FOO]EXEC.MAC;2. 


If you do not specify a file version number, the default is the 
most recent version of the file. 


6.3 CMP SWITCHES 


This section lists the CMP switches, describes the function of 
each one, and gives the default setting for each one. You 
specify switches after the output file in the command line. 


/BL Specifies that blank lines in both files be included in 

/-BL compare processing. If this switch is specified in the 
form /-BL, blank lines are not included in compare 
processing. /-BL is the default switch. 


/CB 
/-CB 


/CO 
/-CO 


/DI 
/-DI 


/FF 
/-FF 


/ul:n 


/UN 
/-ULN 


/MB 
/-MB 


/oL[:au] 


CMP SWITCHES 


Specifies that CMP list infile2 with change bars, in 
the form of exclamation marks (!), to denote which 
lines do not have a corresponding line in infilel. 
When a section of lines in infilel has been deleted in 
infile2 (the output listing file), the first line not 
deleted is marked. /-CB is the default switch. 


You can change the change bar character from the 
exclamation mark to any character you wish by means of 
the /VB switch. 


Specifies that CMP include comments (that is, text 
preceded by a semicolon) in compare processing. /CO is 
the default switch. 


Specifies that CMP list the differences between the two 
files (rather than marking the lines in infile2). /DI 
1s the default switch. 


/CB and /DI are mutually exclusive switches. If you 
specify both, /CB overrides /DI. 


Specifies that CMP include records consisting of a 
Single form-feed character in compare processing. /-FF 
is the default switch. 


Specifies that a number (n) of lines must be identical 
before CMP recognizes amatch. /LI:3 is the default 
Switch. 


When it encounters a match, CMP lists all the preceding 
nonmatching lines, along with the first line of the 
matched sequence of lines to help you find the location 
in the file where the match occurred. 


Specifies that lines in the output file be preceded by 
their line number. Line numbers are incremented by one 
for each record read, including blank lines. /LN is 
the default switch. If you specify /SL, /LN is 
unnecesSary. 


Specifies that CMP include all blank and tab characters 


in a line in compare processing. If you specify /-MB, 
CMP interprets any sequence of blank and/or’ tab 
characters as a single blank character. However, all 


Spaces and tabs are printed in the output listing. /MB 
is the default switch. 


Directs CMP to generate an output file suitable for use 


as SLP command input. When you specify /SL, CMP 
generates the SLP command input necessary to make 
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/TB 
/-TB 


/VB:nnn 


CMP defaul 


Table 6-1: 


CMP SWITCHES 


infilel identical to infile2. If a1- to 8-character 
alphanumeric symbol is included after the /SL switch 
(:au), an audit trail is specified for SLP input. 
Section 6.4.3 gives an example of how CMP generates SLP 
command input. (For information on SLP, see Chapter 
11.) /-SL is the default switch. 


Specifies that CMP include all trailing blanks on a 
line in compare processing. If you specify /-TB, CMP 
ignores all blanks following the last nonblank 
character on a line. When you specify /-CO and /-TB 
together, blanks that precede a semicolon (;) are 
considered trailing blanks and are ignored. /TB is the 
default switch. 


Specifies an octal character code for the character you 
want to use as a change bar. You use this switch with 
the /CB switch. The value nnn specifies the octal 
Character’ code. For example, you can specify /VB:174 
for a vertical bar. /VB:041 (for an exclamation mark) 
is the default switch. 


t switch settings are listed in Table 6-1. 


Summary of CMP Default Switch Settings 


Default Description 


/-BL 
/-CB 
/CO 
/DI 
/-FF 


JiLe3 


/LN 
/MB 


/7-95L 


Do not compare blanks. 

Do not generate change bars. 

Compare comments. 

List only the differences between the two files. 
Do not compare form-feed characters. 


Find three identical lines before a match can 
occur. 


Generate numbered lines. 
Compare all blank and tab characters. 
Do not generate an output file suitable for use as 


SLP command input. 
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CMP SWITCHES 


Default Description 
/TB Compare all trailing blanks. 


/VB:041 Set the exclamation mark (ASCII 041) as the change 
bar character. Used with /CB. 


6.4 FORMATS OF CMP OUTPUT FILES 


CMP uses the two input files you specify on the command line _ to 
create an output file. CMP compares each line in infilel to its 
sequential counterpart in infile2. When there are differences 
between the two files, CMP displays those differences in one of 
three output formats: 


e Differences format (default) (/DI) 
e Change bar format (/CB) 
e SLP command input format (/SL) 
This section gives an example of each of these formats. In the 


examples in the subsequent sections, the following files are used 
as infile1l (TEST1.DAT;1) and infile2 (TEST2.DAT;1): 


DW1i: [USERFILES ]TEST1.DAT;1 | DW1i: [USERFILES ] TEST2.DAT;1 
LINE1 LINE1 
LINE2 LINE2 
LINE3 LINE3 
LINE4 LINE4 
LINES LINES 
12345 45678 
23456 56789 
34567 O1reg1 
LINEQ LINEY 
LINE10 LINE10 
LINE11 LINE11 
EXTRA EXTRA 

EXTRA 
EXTRA 
EXTRA 


FORMATS OF CMP OUTPUT FILES 


6.4.1 Differences Format 


If you enter a command line and do not specify any switches, CMP 
lists the differences between the two files on your terminal 
screen or in an output file. The differences are listed in 
pairs; Eirse, the lines from infilel that do not have 
counterparts in infile2 are listed, then the lines from infile2 
that do not have counterparts in infilel are listed. Each set of 
lines is terminated by the first line (or set of lines) for which 
a match is successful. 


The following example shows the format of output generated 
without any switches. The output file is generated with the CMP 
command: 


CMP>TESTDIF.DAT=TEST1.DAT,TEST2.DAT 


KKK KKK KKK RRA KKK KKK RAK KKK RRR RRR KKK KKRKKKKK KKK 
1) DW1:[USERFILES]TEST1.DAT;1 


6 12345 
yi 23456 
8 34567 
9 LINEY 


KRREREKKKKKKRKKKKRKKKK 
2)  DW1:[USERFILES]TEST2.DAT;1 


6 45678 
7 56789 
8 67891 
9 LINEY 


KREKEKEKKEKRKKKRKRKKKRKRERREKRKRKEEKREKREKKEKEKRKKRKEKKEKRKKKKREKE 


1)  DW1:[USERFILES]TEST1.DAT;1 
KREKKKKRKKRKRKKEKKEKEEKK 
2) DWl:[USERFILES]TEST2.DAT;1 
13 EXTRA 
14 EXTRA 
15 EXTRA 


2 differences found 


The input files are TEST1.DAT and TEST2.DAT, which are shown in 
Section 6.4. There are two sets of differences separated by a 
long line of asterisks. (When there are several sets of 
differences, CMP separates each set from the next set by a long 
line of asterisks.) The short line of asterisks separates’ the 
pair of differences that comprise the set. 


Note that because /LI:n was not specified, the number of lines 
required for a match defaults to 3. Thus, CMP found two 
differences. 


FORMATS OF CMP OUTPUT FILES 


6.4.2 Change Bar Format 


You use the /CB switch to generate a listing containing change 
bars that show the differences between two files. In the CMP 
command line, infile2 is the listing you want generated. 


The following example shows the format of output with change bars 

applied to lines from two files that do not match line for line. 

The output file is generated with the CMP command: 
CMP>TESTDIF.DAT/CB=TEST1.DAT,TEST2.DAT 


Notice that the change bar is applied to the first line of match 
(line 9). 


1 LINE1 
Z LINE2 
3 LINE3 
4 LINE4 
5 LINES 
6 | 45678 
yy 4 96789 
8! 67891 
gy. 3 LINEY 
10 LINE10 
11 LINE11 
12 EXTRA 
13 ! EXTRA 
14 ! EXTRA 
A> 4 EXTRA 


2 differences found 


6.4.3 SLP Command Input Format 


You use the /SL[:au] switch to generate a file containing records 
to be used as SLP command input. /SL directs CMP to generate the 
SLP edit command lines and input lines required to make infilel 
identical to infile2. 


After executing CMP, you execute SLP (CMP does not generate an 
SLP command line). For a complete description of the SLP 


utility, see Chapter 11 in this manual. 


FORMATS OF CMP OUTPUT FILES 


The following example shows the format of output generated using 
the /SL switch. The output file is generated with the CMP 
command: 


CMP>TESTDIF.DAT/SL: BLSO0O01=TEST1.DAT,TEST2.DAT 
-6,8,/;BLS001/ 

45678 

56789 

67891 

=12;,,/;BLSO01L/ 

EXTRA 


EXTRA 
EXTRA 


a 


6.5 CMP MESSAGES 

This section lists the CMP messages, gives a brief description of 
the condition that causes each message, and suggests a response 
to the condition. 

CMP -- n differences found 


Explanations CMP found n differences between the two files. 


User Action: This is an informational message. 


CMP -- Command syntax error 
Explanation: CMP found an error in the command line syntax. 
User Action: Check the syntax of the command line 


specification and reenter the command line using the correct 
syntax. 


CMP -- Error reading input file 


Explanation: An I/O error occurred while CMP was reading an 
input file. 


User Action: Reenter the command line. 


CMP MESSAGES 


CMP -- Error writing output file 


Explanations: An I/O error occurred while CMP was writing 
the output file. 


User Actions The output device may be full or bad. Check 
this, then reenter the command line. 


CMP -- Illegal /LI value 


Explanation: You specified a negative value for the number 
of lines required for a match. 


User Action: Reenter the command line with a legal value 
specified. 
CMP -- Illegal switch or switch value 


Explanation: An illegal switch or switch value was entered 
in the command line. 


User Actions Reenter the command line using a legal switch 
Or switch value. 


CMP -- Open failure on input file #1 
Explanation: CMP could not open the first input file. 
User Action: Check the file specification for the first 
input file and reenter the command line using the correct 
file specification. 

CMP -- Open failure on input file #2 
Explanation: CMP could not open the second input file. 
User Action: Check the file specification for the second 
input file and reenter the command line using the correct 
file specification. 

CMP -- Open failure on output file 
Explanation: CMP could not open the specified output file. 
User Actions: Check the file specification for the output 


file and reenter the command line using the correct file 
Specification. 


CMP MESSAGES 


CMP -- Too many differences for available core 


Explanations: The files were too dissimilar for CMP to fit 
all the differences in memory. 


User Actions You cannot compare the two files. 


CHAPTER 7 
FILE DUMP UTILITY (DMP) 


The File Dump Utility (DMP) enables you to examine the contents 
of a specific file or volume of files. You can format the output 
in ASCII, octal, decimal, hexadecimal, or Radix-50 form and dump 
it to any suitable output device, such as a printer, terminal 
screen, or disk. 


You can dump the header and/or virtual blocks of a file or only 
the virtual records of a file. If you are dumping a volume, you 
can specify a range of logical blocks. DMP handles blocks of up 
to 256 (decimal) words in length. The maximum block size must 
not exceed this length. | 


DMP operates in two basic modes: file mode and device mode. Use 
file mode to dump virtual records or virtual blocks; use device 
mode to dump logical blocks. 


File Mode In file mode, one input file is specified, 
and all or aespecified range of virtual 
blocks are dumped. You can also dump all the 
virtual records of a specified file in this 
mode. The input device must be a FILES-11 
formatted disk. 


In file mode, you can specify that data _ be 
dumped one record or one block at a time. A 
virtual block or record refers to one _ block 
or record of data ina file. Virtual blocks 
and records are numbered sequentially from 1 
through n, where n is the total number of 
blocks or records in the file. Virtual block 
0 contains the header of the file. Use the 
/BL:n:m switch to dump virtual blocks and the 
/RC switch to dump virtual records. The /BL 
and /RC switches are mutually exclusive. 
(DMP switches are listed in Section 7.3.) 


Device Mode In device mode, you specify only the 


input 


device, and a specified range of logical 


blocks is dumped. The /BL:n:m switch 
required parameter in this mode. 


a 


A logical block refers to a physical 512-byte 
block on disk. Logical blocks are numbered 
from 0 to n-1, where n is the total number of 


logical blocks on the device. 
NOTE 


The volume must be mounted foreign. 


7.1. INVOKING DMP 


You can invoke DMP in two ways: 


1. Invoke the DUMP command, which in turn invokes’ DMP. 
Chapter 3 for a description of the DUMP command. 


2. Invoke DMP directly from the DCL command level. 
To invoke DMP directly from the DCL command level, enter 
following command: 


S RUN SDMP 


You receive a new prompt to indicate that you are in the 
environment: 


DMP> 


See 


the 


DMP 


Once you are in the DMP environment, DMP waits for your command. 


The following section describes the command format. 


7.2 DMP COMMAND FORMAT 
The format for a DMP command is: 


[outfile][/sw][/sw...]J=inspec[{/sw][/sw...] 


DMP COMMAND FORMAT 


outfile 


Specifies the output file. If the output file name and file 
type are unspecified, DMP creates the file DMPFIL.DMP. TI: 
(terminal) is also an acceptable outfile specification. 


/SW 


Specifies one of the switches listed in Section 7.3. Unless 
otherwise indicated in a switch description, all switches 
can be applied either to the input file or to the output 
file with equal effect. DMP will allow multiple dumps ina 
Single command line. Therefore, any or all of the current 
format switches may be specified. Certain switches are 
mutually exclusive. For example, the /HX, /LW, and /WD 
Switches are mutually exclusive hexadecimal dump switches. 
The first one in the following order will be the only one 
executed: /LW, /WD, /HX. 


inspec 


Specifies the input device and file or input device only. 
In file mode, the equal sign and the input file name and 
file type are required because DMP does not provide a 
default for either of them. However, the input file version 
number defaults to the latest version and the device 
defaults to SY: and the current directory. 


In device mode, the equal sign and input device are required 
as is the /BL:n:m switch which specifies the range of 
logical blocks to be dumped. 


For a complete description of file specifications, see the Tool 
Kit User’s Guide. 


7.3 DMP SWITCHES 


DMP switch specifications consist of a slash (/) followed by a 
switch name, optionally followed by a value. The value is 
separated from the switch by a colon (:). DMP functions are 
implemented by the following switches: 


Default The default is a word mode octal dump. 


JAS 


/BA:n:m 


DMP SWITCHES 


Specifies that the data should be dumped 
one byte at a time in ASCII mode. The 
control characters (Q-37 octal) are 
printed as eight-bit characters consisting 
of a circumflex (*), followed by the 
alphabetic character corresponding to the 
Character code plus i100 Octal. For 
example, bell (code 7 octal) is printed as 
*G (code 107 octal). Lowercase characters 
(140-177 octal) are printed as a percent 
Sign (%), followed by the corresponding 
uppercase character (character code minus 
40 octal), unless the /LC switch is 
Specified. DMP will also display the DEC 
Multinational Characters. 


NOTE 


The /AS and /OCT switches are 
mutually exclusive when dumping 
bytes. 


Specifies a 2-word base block address (the 
initial base address is 0,0), where n is 
the high-order base block address (octal), 
and mis the low-order base block address 


(octal). The address may also be 
specified in decimal by using a period 
after the number. All future block 


numbers specified by the /BL switch will 
be added to this value to obtain an 


effective block number. This switch 1s 
useful for specifying block numbers’) that 
exceed 16 bits. For example: 


DMP>/BA:1:0 


specifies that all future block numbers 
will be relative to 65536 decimal (200000 
octal). 


DMP> /BA:0:0 


clears the base address. Once the /BA 
Switch is specified, it remains in effect 
until it is used again to set a new base 
address. 


/BL:n:m 


Zor 


FOC 


/F®I:file-number: 


sequence-number 


/HD[:F or :U] 


DMP SWITCHES 


When the /BA switch appears in a command 
line, no blocks are dumped. The only 
result of the command line is to set the 
base address. 


Specifies the range of blocks to be 
dumped, where nis the first block and m 
is the last block. The values of n and mom 
must not exceed 16 bits. In file mode 
only, the /BL switch is not required. If 
the /BL switch is not specified, DMP will 
dump all blocks of the specified file, 
relative to the current base address. 


If /BL:n:m is specified in file mode, it 
specifies the range of virtual blocks to 
be dumped. If /BL:n:m is specified as 
/BL:0 in file mode, no virtual blocks are 
dumped. This is useful for dumping only 
the header portion of the file (see /HD). 
The /BL switch and the /RC switch are 
mutually exclusive. 


The /BL:n:m switch is a required parameter 
in device mode. When used in device mode, 
it specifies the range of logical blocks 
to be dumped. 


The value n represents the block number of 
the first block dumped. Successive blocks 
are labeled with a block number one higher 
than the preceding block number. The dump 
will continue until the block labeled mis 
dumped. 


Specifies that the data be dumped in octal 
byte format. 


Specifies that the data be dumped in 
decimal word format. 


In file mode, the file number’ can be used 
instead of a file name as a file 
specification for input. 


This switch is an optional parameter used 
in file mode. If specified, the /HD 
Switch causes the file header as well as 
the specified or implied portion of the 


file to be dumped. Example: 


/HE 


/HX 


JID 


/UB 


DMP SWITCHES 


DMP>TI:=JMF.DAT/HD/BL:5:6 


This example dumps the header of JMF.DAT 
in header format and virtual blocks 5 and 
6 in octal format. 


In addition, this switch has two options. 
af ar the default, causes a FILES-1i1 
formatted dump of the header. 9 fi 
specifies an unformatted octal dump. An 
octal dump also occurs when DMP is used on 
non-FILES-11 headers. 


If you want only the header portion of the 
file to be dumped, specify: 


/HD/BL:0 


Specifies the format for data blocks’ that 
have the FILES-11 header structure. Other 
blocks are output as a data dump in the 
format selected by /AS, /BY, and so on, in 
default octal words. 


Example: 
DMP>HEAD.LST=[0,0]INDEXF.SYS/HF 


This example generates a dump of the index 
file INDEXF.SYS and formats all the 
headers in the file. 


Specifies that the data be dumped in 
hexadecimal byte format. Note that a 
hexadecimal dump reads from right to left. 
(See also the /LW and /WD switches.) 


Causes DMP’s version to be identified. 
This switch may be specified on a command 
line by itself at any time. 


Example: 


DMP>/ID 
DMP--DMP VERSION M07.1C 


Requests logical block information for a 
file. The starting block number anda 
contiguous or noncontiguous indication for 
the file are displayed. 


/LC 


/LIM:n:m 


/ LW 


/MD[:n] 


/OCT 


/RD 


/RC 


DMP SWITCHES 


Example: 


DMP>TI:=RICKSFILE.DAT;3/LB 
STARTING BLOCK NUMBER = 0,135163 C 


The file RICKSFILE.DAT, version 3, is a 
contiguous file starting at block number 
0,135163. (See /BA:n:m for block number 
description. ) 


Specifies that the data should be dumped 
in lowercase characters. 


Specifies the range of bytes, n through n, 
of each record or block to be dumped. The 
default remains /OCT if you do not specify 
format switches. 


Specifies that the data be dumped in 
hexadecimal double-word format. 


Specifies a memory dump and allows control 


of line numbers. Line numbers are 
normally reset to zero whenever ae block 
boundary is crossed. The /MD switch 


allows lines to be numbered sequentially 
for the full extent of the file, that is, 
the line numbers are not reset when block 
boundaries are crossed. The optional 
value (:n) specifies the value of the 
first line number. The default is 0. The 
/MD switch is used with the output file 
specification. 


Specifies that the data should be dumped 
in octal format in addition to other 
formats specified. If no DMP format 
Switches are specified, the default is 
octal. The /AS switch and the /OCT switch 
are mutually exclusive when dumping bytes. 


Specifies that data be dumped in 
Radix-50-format words. 


Specifies that data be dumped a record at 
a time (rather than a block at a time). 
The data format is determined by setting 
any of these format switches: /AS, /DC, 
/HX, /LW, /R5, or /WD. 


DMP SWITCHES 


The largest record that DMP can process is 
limited by the amount of space available 
to the DMP task. DMP’s task image has 512 
(decimal) bytes allocated to it initially. 


The /RC switch and the /BL switch are 
mutually exclusive. 


/WD Specifies that the data be dumped in 
hexadecimal word format. 


7.4 DMP EXAMPLES 


Three examples of dump listings are included in this section to 
illustrate how the various DMP switches can be used. DMP edits 
blocks or records 16 (decimal) bytes at a time. The dump 
includes the indicated number of valid bytes in the block or 
record. The remaining number of bytes are listed as null bytes 


(QO). 


7.4.1 A Multiple Format Dump 

The following command line shown dumps virtual blocks 5 and 6 of 
DSC.MAC in hexadecimal, Radix-50, and decimal format. Each line 
of the output file will appear in three different formats. 


DMP>DOC.DMP=[USERFILES ]DSC.MAC/HX/R5/DC/BL: 5:6 
The contents of DOC.DMP are: 


DUMP OF DW1:[USERFILES]JDSC.MAC;1 - FILE ID 17725,11,0 
VIRTUAL BLOCK 0,000005 - SIZE 512. BYTES 


4E 41 4D 4D 4F 43 20 41 20 3B 00 1E 53 45 52 49 0000 *HX 
000000 MFY ML7 0 EFK EFQ LSK LN/ LT3 °R5 
0. 21065. 21317. 00030. 08251. 08257. 20291. 19789. 20033.;DC 
53 45 53 53 45 43 4F 52 50 20 44 4E 41 20 2c 44 0010 

000020 GCL JP2 J7F L22 L$Z KCK MMK ML7 

16. 11332; 16672. 17486.. 20512. 20306... 17732: 212331. 21327. 

53 52 49 46 20 3B 00 39 00 3B 00 O01 2E 54 49 20 0020 


DMP EXAMPLES 


DUMP OF DW1:[USERFILES]DSC.MAC;1 - FILE ID 17725,11,0 


VIRTUAL BLOCK 0,000006 - SIZE 512. BYTES 
20 44 4EF 46 55 42 24 20 51 45 20 30 52 20 46 49 0000 
000000 KI3 MEX EF M E E1H MYZ LT8 EFT 
0. 17993. 21024. 08240. 20805. 09248. 21826. 20038. 08260. 
44 4E 45 09 00 09 50 4F 4F 4c 20 45 56 41 45 4c 0010 
000020 KCT M2A EFU LST L39 I KA3 J7F 
16. 17740. 22081. 08261. 20300. 20559. 00009. 17673. 17486. 
54 53 24 20 54 45 4c 09 00 2B 00 50 4F 4F 4c 20 0020 
7.4.2 A Record Dump 
The following command line dumps all of the virtual records of 
YACHT.SEQ in ASCII and decimal word format: 

DMP>REC .DMP=[USERFILES ] YACHT. SEQ/RC/AS/DC 
The contents of REC.DMP are: 
DUMP OF DW1:[(USERFILES]YACHT.SEQ;1 - FILE ID 15451 5.350 
RECORD NUMBER O01. - SIZE 41. BYTES 
000000 A L B E R G 3. ‘7 M K 
O. 19521. 17730. 18258. 08224. 08224. 14131. 19744. 0826/7. 
000020 1 « K £&£ fT -¢€ oH 3 7 2 0 O 
16. 18761. 08224. 17739. 17236. 08264. 14131. 12832. 12336. 
000040 O 0 i1 2 3 6 9 5 17@7@7@ 74 *@ *@ *@ 
32% 12336. 12849. 13875. 13625. 00049. 00000. 00000. OQ0000. 
RECORD NUMBER 02. - SIZE 41. BYTES 

000000 A L B I# #N 7 9 
QO. 19521. 18754. 08270. 08224. 08224. 14647. 08224. 08224. 
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000020 5S kb O O--P 2 6 0 4 2 
EO. 06224. 08224. 19539. 203034. 08272. 13874. 12320, 12852. 


000040 0 0 1 0 141 7 9 0 07@7*@ *@*@ *@ *@ *@ 
Svar 12336. 12337. 14129. 12345. 00048. 00000. 00000. 00000. 


7.4.3 A Header Dump 
The following command line dumps only the header of DSC.MAC. 


DMP> DHR.DMP=[USERFILES]DSC.MAC/HD/BL:0 


The contents of DHR.DMP are: 
DUMP OF DW1:[USERFILES]DSC.MAC;1 - FILE ID 17725,11,0 
FILE HEADER 


HEADER AREA 


H.IDOF 027 

H.MPOF 056 

H.FNUM, 

H.FSEQ (17725,11) 

H.FLEV 401 

H.FOWN [200,200] 

H.FPRO [ RWED, RWED, RWED, RWED] 

H.UCHA 000= 

H.SCHA 000 = 

H.UFAT 
F.RTYP 002 = R.VAR 
F.RATT 002 = #£FD.CR 
F.RSIZ 116 = 78. 
F.HIBK H:0 L:000040 = 32. 
F.EFBK H:0 L:000040 = 32. 
F.FFBY 532 = 346 
(REST) 
000000 000000 000000 000000 000000 000000 000000 0000 
000000 

IDENTIFICATION AREA 

I.FNAM, 

I.FTYP, 

I.FVER DSC .MAC;1 

I .RVNO 1 

I.RVDT 13-oOcT-80 

I.RVTI 09:52:46 

I.CRDT 13-OCT-80 

I.CRTI 09:52:45 

I. EXDT ae 
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MAP AREA 
M.ESQON 000 
M.ERVN 000 
M.EFNU, 
M.EFSQ (0,0) 
M.CTSZ 001 
M.LBSZ 003 
M.USE O14 = 12. 
M.MAX 314.= 204: 
M.RTRV 
SIZE LBN 
2 H:000 L:036215 = 15501 
3. H:000 L:036235 = 15517 
i H:000 L:036250 = 15528 
Ze H:000 L:036272 = 15546 
Se H:000 L:036313: = 15563... 
11. H:000 L:036411 = 15625. 
CHECKSUM 
H.CKSM 122620 


7.5 DMP ERROR MESSAGES 


DMP -- BAD DEVICE NAME 


Explanation: An incorrect device name was entered in a file 


specification. 


User Actions: Reenter the command line specifying 
correct device. 


DMP -- BLOCK SWITCH REQUIRED IN LOGICAL BLOCK MODE 
Explanations /BL must be specified. 


User Actions Reenter the command line specifying the 
Switch. 


DMP -- CANNOT FIND INPUT FILE 


Explanation: The requested file cannot be located in 
specified directory. 


User Action: Reenter the command line specifying 
correct file name and directory. 


DMP -- COMMAND SYNTAX ERROR 
Explanation: A command line was entered in a format 


does not conform to syntax rules. 
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the 


/BL 


the 


the 


that 


DMP 


DMP 


DMP 


DMP 


DMP 


DMP 


User Action: 


DMP ERROR MESSAGES 


Reenter the command line specifying 


COPrrect: syntax. 


- FAILED TO ASSIGN LUN 


Explanations: 
specification. 


User Action: 


An illegal device was entered in a 


Reenter the command line specifying 


correct device. 


- FAILED TO READ ATTRIBUTES 


Explanations 


A file was specified for which you _ did 


have read access privileges. 


User Action: 
protection of 


Rerun DMP after you have changed 
the file to READ access. 


-- ILLEGAL SWITCH 


Explanation: 


Switch, or a legal switch was used in an invalid manner. 


User Actions: 


the 


file 


the 


not 


the 


A switch was specified that is not a valid DMP 


Reenter the command line specifying 


correct switch. 


- ILLEGAL USE 


Explanation: 


OF /RC SWITCH 


The /RC switch can be used only in file 


(see the beginning of this chapter). 


User Actions 
name. 


Reenter the command line specifying a 


- ILLEGAL VALUE ON HD SWITCH 


Explanations: 


An option was entered other than F or U 


the /HD switch. 


User Actions 


Reenter the command line specifying 


correct option. 


- I/O ERROR ON INPUT FILE 


or 


- I/O ERROR ON OUTPUT FILE 


Explanation: 


One of the following conditions exists: 


the 


mode 


file 


for 


the 
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A problem exists on the physical device. 
The file is corrupted or the format is incorrect. 


The output volume is full. 


User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


DMP -==-NO “INPUT FILE SPECIE IED 


Explanation: A command line was entered with no input’ file 
specification. 


User Actions Reenter the command line specifying an input 
file. 


DMP -- NO LISTS OR WILD CARDS ALLOWED 


Explanation: Either a command line with more than one input 


or 


output file name was entered, or a wildcard was entered 


as a file specification. 


User Actions Reenter the command line, specifying only one 
input file specification and one output file specification. 
No wildcard specifications are allowed. 


DMP -- OPEN FAILURE ON INDIRECT FILE 


Explanation: The requested indirect command file does not 
exist as specified. One of the following conditions exists: 


The file is protected against access. 

A problem exists on the physical device. 

The volume is not mounted. 

The specified file directory does not exist. 


The named file does not exist in the specified 
directory. 


User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


DMP -- OPEN FAILURE ON INPUT FILE 
or 
DMP -- OPEN FAILURE ON OUTPUT FILE 


1h 


DMP ERROR MESSAGES 


Explanation: One of the following conditions exists: 


The file is protected against access. 
A problem exists on the physical device. 


The named file does not exist in the specified 
directory. 


The volume is not mounted. 


The specified file directory does not exist. 


User Actions: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


CHAPTER 8 
LIBRARIAN UTILITY PROGRAM (LBR) 


The Librarian Utility Program (LBR) allows you to create, update, 
modify, list, and maintain library files. A library file is a 
direct access file that contains a collection of related files. 
LBR organizes files, usually having the same file type, into 
library modules so that you have rapid and convenient access to 
your files. 


Library files contain two directory tables: the Entry Point 
Table (EPT) and the Module Name Table (MNT). The EPT contains 
entry point names that consist of global symbols defined as entry 
points in MACRO source programs. The MNT contains names of the 
modules in the library. Both tables are alphabetically ordered. 


There are three kinds of library files: object, macro, and 
universal, described below. 


Object library © contain object files (.OBJ). The module 

files (.OLB) names are derived from .TITLE directives, while 
the entry point names are derived from global 
symbols defined in the module. LBR_ references 
the module code in the library by the module 
name. The source program references object 
library modules by the entry point name. Entry 
points apply only to object libraries. 


You use object module libraries as input to the 
Professional Application Builder (PAB). PAB 
searches for definitions of all global symbols 
referenced in a program in the following 
manner. First, PAB searches the other modules 
specified, then it searches the specified 
user-written object module Library, and 
finally, it searches the system library. 


Macro library contain source macro files (.MAC). The module 

files (.MLB) names are derived from .MACRO directives. From 
each macro definition, LBR extracts the name 
and creates an entry in the module name table. 
The entry in the module name table is the means 
by which the assembler finds the associated 
macro definition in the library. 


You use macro library modules as input to the 
Professional MACRO-11 Assembler. The assembler 
searches the specified library for macros 
listed in .MCALL statements and called in the 
source program before searching the system 
macro library. 


Universal contain modules inserted from any kind of file, 
library whether it be a program or text. The module 
files (.ULB) names are either user-specified in the Insert 


(/IN) Switch, or derived from the file name at 
the time of insertion. 


Primarily, you use universal libraries to 
package related files together. You ‘Can 
reference a universal library module in a 
program by using the Universal Library Access 
(SULA) system library routine. SULA, specified 
in the macro source program, establishes the 
necessary conditions for access (read-only) to 
a universal library module. 


Section 8.3 describes how you invoke LBR. 


8.1 FORMAT OF LIBRARY FILES 


A library file consists of a library header, an entry point 
table, a module name table, the library modules and their 
headers, and any available space. 


The entry point table has zero length for macro and _ universal 


libraries. Figure 8-1 illustrates object and macro library file 
format. Figure 8-2 illustrates universal library file format. 


8.1.1 Library Header 
The header section is ae full block in which the first 24 


(decimal) words are used to describe the current status of the 
library. The header’s contents are updated as the library is 
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modified. This allows LBR to access the necessary information to 
perform its functions (for example, Insert, Compress, and 
Delete). The twenty-fourth word in the library header is the 
default insert file type for universal libraries and is undefined 
for macro and object libraries. See Figure 8-3. 


8.1.2 Entry Point Table 


The entry point table consists of 4-word elements containing an 
entry point name (words 0-1) and a pointer to the module header 
of the module where the entry point is defined (words 2-3). see 
Figure 8-4. This table is searched when a library module is 
referenced by one of its entry points. The table is sequenced in 
order of ascending entry point names. The entry point table 
applies only to object library files. 


8.1.2.1 Module Name Table - The module name table is searched 
when the library module is referenced by its module name rather 


than by one of its entry points. It is made up of 4-word 
elements: a module name (words 0-1) and a pointer to the module 
header (words 2-3). See Figure 8-5. The module name table is 


sequenced in order of ascending module names. 


8.1.2.2 Module Header - Each module starts with a header of 
eight words for object and macro modules and 32 (decimal) words 
for universal modules. The module header contains information 
about the module such as the type and status of the module, its 
length (number of words), and its attributes. See Figures 8-6 
and 8-7. 


In object and universal modules, the low-order bit of the 
attributes byte is set if the module has the selective search 
attribute. In universal modules, bit 1 of the attributes byte is 
set if the input file was contiguous. Also, in object modules, 
the two words of type-dependent information contain the module 
identification defined by the .IDENT directive at assembly time. 
In macro modules, these two words are undefined. 


For universal modules, type-dependent identification is derived 
from the file type and version number of the input file. 


Universal libraries allow you to change the module header, which 
contains optional descriptive information, by means of the Modify 
Header switch (/MH). 


FORMAT OF LIBRARY FILES 


LIBRARY 
HEADER 


ENTRY POINT 
TABLE 


BLOCK 


BOUNDARIES 
MODULE NAME 


TABLE 


VARIABLE- MODULE 1 HEADER 
LENGTH 
RECORDS 


MODULE 1 


MODULE N HEADER 


MODULE N 
AVAILABLE SPACE 


ZK-184-81 


Figure 8-1: General Format for Object and Macro Library Files 
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ENTRY POINT 


TABLE 
BLOCK 


BOUNDARIES 
MODULE NAME 
TABLE 


VARIABLE- MODULE 1 HEADER 
LENGTH UNUSED SPACE 
RECORDS 


MODULE 1 


UNUSED SPACE 


MODULE 2 HEADER 
UNUSED SPACE 


MODULE 2 


UNUSED SPACE 


MODULE N HEADER 
UNUSED SPACE 


MODULE N 


AVAILABLE SPACE 


NOTE 


All universal module headers and the first record 
of each universal module will start on a block 
boundary. 


Figure 8-2: Universal Library File Format 
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OFFSET 

2 LBR (LIBRARIAN) VERSION 

4 (. IDENT FORMAT) 

6 

10 DATE AND 

12 TIME LAST 

14 INSERT HOUR 
16 MINUTE 

20 SECOND 
; 
: 
: 
: 
; 
? 
: 
42 LOGICALLY DELETED 
44 AVAILABLE (BYTES) 
46 CONTIGUOUS SPACE 

50 AVAILABLE (BYTES) 

a2 NEXT INSERT RELATIVE BLOCK 

54 START BYTE WITHIN BLOCK 
: 


LUNDEFINED FOR MACRO AND OBJECT LIBRARIES 
ZK-186-81 


Figure 8-3: Contents of Library Header 
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WORD 0 GLOBAL SYMBOL 
] NAME (RADS5QO) 
Z ADDRESS OF RELATIVE BLK. 
MODULE 
3 HEADER BYTE IN BLOCK 


ZK-187-81 


Figure 8-4: Format of Entry Point Table Element 


reset 


WORD 0 MODULE NAME 
1 (RADSO) 
2 ADDRESS OF RELATIVE BLK. 
MODULE 
3 HEADER BYTE IN BLOCK 


ZK-188-81 


Figure 8-5: Format of Module Name Table Element 
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OFFSET FROM 
START OF 
MODULE HEADER 


ATTRIBUTES STATUS O=NORMAL MODULE 
1=DELETED MODULE 


SIZE "OF 


MODULE. (BYTES) 


DATE 
MODULE 
INSERTED 


TYPE DEPENDENT 


INFORMATION 


ZK 189-81 


Figure 8-6: Module Header Format for Object and Macro Libraries 
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OFFSET FROM 
START OF 
MODULE HEADER 


0 ATTRIBUTES STATUS 
2 SIZE OF 

4 MODULE (BYTES) 

6 | DATE YEAR 

19 MODULE MONTH 
12 INSERTED DAY 

14 IDENT 

16 


20 OPTIONAL 


22 


24 OPTIONAL 


26 


30 OPTIONAL 


32 


34 OPTIONAL 


36 
49 
USER 
42 FILE 
44 ATTRIBUTES 
76 


Z2K-190-81 


Figure 8-7: Module Header Format for Universal Libraries 
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Note to Figure 8-7 

Locations 40 (octal) through 76 (octal) contain user file 
attributes. User file attributes comprise the first of five 
sections in the FDB of the original file from which the module 
was created. The user file attributes are: 

e Record type 

@ Record attribute 

@e Record size 

@e Highest virtual block 

@e End of file block number 

@® Optional information 
When you create a file and insert it into a universal library, 
LBR copies the input file attributes to the module header. You 


can modify some of these attributes by using the modify header 
Switch (/MH). 


8.2 LBR RESTRICTIONS 

The following restrictions apply when using LBR: 
@e Limit of 65,536 (64K) words per module. 
@e Limit of 65,536 (64K) blocks per library. 


e Tables should be allocated their anticipated maximum size. 
Expanding table allocations requires using the Compress 
Switch (/CO) to copy the entire file. 


e A fatal error results if an attempt is made to insert a 
module into a library that contains a module with a different 
name from, but with the same entry point as, the inserted 
module. For further information, refer to the discussion of 
the /IN switch in Section 8.5.8. 


e The use of wildcards in file specifiers is not allowed (that 
is, forms such as *.OBJ, where the * indicates all modules 


with type .OBJ). 


LBR RESTRICTIONS 


The library’s tables must contain enough space for both the 
modules being replaced and their replacements, because the new 
modules are entered and the old modules are only logically (not 
physically) deleted. 


8.3 INVOKING LBR 
You can invoke LBR in two ways: 


1. Invoke one of the LIBRARY commands, which in turn invokes 


LBR. See Chapter 3 for a description of the LIBRARY 
commands. 


2. Invoke LBR directly from the DCL command level. 
To invoke LBR directly from the DCL command level, enter’ the 
following command: 

S RUN SLBR 


You receive a new prompt to indicate that you are in the LBR 
environment: | 


LBR> 


Once you are in the LBR environment, LBR waits for your command. 
LBR accepts command lines in the following general format: 


outfile[{,listfile]J=infileil[,infile2,...infilen] 


LBR allows only one level of indirect command file nesting. 


8.4 DEFAULTS FOR LBR FILE SPECIFIERS 


Table 8-1 describes the defaults for LBR file specifiers. 


DEFAULTS FOR LBR FILE SPECIFIERS 


Table 8-1: LBR File Specifiers Defaults 


Specifier Default 


dev: Output File 
S10 


Listing File 
The device that was specified for the 
output file; otherwise, the default for 
the output file. 


Input File 
For the first input file specifier, Sy0:. 


For subsequent input file specifiers, the 
device specified in the previous input 
file specifier; otherwise, the default for 
the previous input file specifier. 


[dir] Output File 
The default directory under which LBR is 
currently running. 


Listing File 
The directory that was specified for the 
output file; otherwise, the default for 
the output file specifier. 


Input File 
For the first input file specifier, the 
directory under which LBR is currently 
running. 


For subsequent input file specifiers, the 
directory specified in the previous input 
file specifier; otherwise, the default for 
the previous input file specifier. 


filename No default. Must be specified. 
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Specifier Default 


. type Output File 
Depends on the default in effect (see 
Section 8.5.4), except when the Compress 
(/CO) or Create (/CR) switch is specified 
(see Sections ope Peek and 8 .c5S2- 
respectively). 


Listing File 
-LST 


Input File 
Refer to the descriptions of Compress 
(Section 8.5.1), Insert (Section 8.5.8) 
and Replace (Section 8.5.12) switches. 


sver Latest version of the file, or latest version 
plus 1 for the output file when the Compress 
(/CO), Create (/CR), or Extract (/EX) switches 
are specified. 


/switch Output File 
JIN (Insert) 


List File 
/uI (List module names) 


Input File 
None 


8.5 LBR SWITCHES 


LBR uses switches appended to file specifications to invoke 
functions. These switches are summarized in Table 8-2. 


LBR SWITCHES 


Table 8-2: LBR Switches 


Option Switch Function 

Compress /CO Compress a library file. 

Create 7 CR Create a library file. 

Delete /DE Delete a library module and all its 


entry points. 


Default /DE Specify default library file type. 
Delete Global /DG Delete a library module entry point. 
Entry Point /EP Include entry point elements in the 


library entry point table. 


/-EP Exclude entry point elements in the 
library entry point table. 


Extract /EX Extract (read) one or more modules 
from a library file and write them 
into a specified output file. 


Insert JIN Insert a module. 
List Jul List module names. 
/LE List module names and entry points. 
/FU List module names and full module 
description. 
Modify Header /MH Modify a universal module header. 
Replace /RP Replace a module. 
/-RP Do not replace a module. 
Selective Search JSS Set the selective search attribute 


in the module header. 
Squeeze racy Reduce the size of the macro source. 


/-SZ Do not reduce the size of a specific 
macro source. 


LBR SWITCHES 


8.5.1 Compress Switch (/CO) 


Use the Compress switch (/CO) to physically delete all logically 
deleted records, to put all free space at the end of the file, 
and to make the free space available for new library module 
inserts. Additionally, the library table specification may be 
altered for the resulting library. LBR accomplishes this by 
creating anew file that is a compressed copy of the old library 
file. The old library file is not deleted after the new file is 
created. 


The /CO switch can be appended only to the output file 
Specification. The format for specifying the /CO switch is: 


outfile/CO:size:ept:mnt=infile 


outfile 


Specifies the file that is to become the compressed version 
of the input file. The default file type is .OLB if the 
input file is an object library, .MLB if the input file is a 
macro library, or .ULB if the input file is a universal 
library. 


/CO 


Specifies the Compress switch. 


ssize 


Specifies the size of the new library file in 256 
(decimal)-word blocks. The size of the old library file is 
the default size. 


sept 


Specifies the number of Entry Point Table (EPT) entries to 
allocate. If the value specified is not a multiple of 64 
(decimal), the next highest multiple of 64 (decimal) is 
used. The number of EPTs in the old library file is the 
default value. This parameter is always forced to zero for 
macro libraries and universal libraries. The maximum number 
of entries is 4096 (decimal). 


LBR SWITCHES 


smnt 


Specifies the number of Module Name Table (MNT) entries to 


allocate. If the value specified is not a multiple of 64 
(decimal), the next highest multiple of 64 (decimal) is 
used. The number of MNTs in the old library file is the 
default value. The maximum number of entries is 4096 
(decimal). 
infile 

Specifies the library file to be compressed. The default 
file type is .OLB for object libraries, .MLB for macro 
libraries, and .ULB for universal libraries. The actual 


default file type is determined by the current default 
library file type (see Section 8.5.4). 


Example 
LBR>RICKLIB/CO:100.:128.:64.=SHEILA.OLB 


In this example, file SHEILA.OLB is compressed, and a new 
file, RICKLIB.OLB, is created with the following attributes: 


size = 100 (decimal) blocks 
EPT = 128 (decimal) entry points 
MNT = 64 (decimal) module names 


The new file, RICKLIB.OLB, receives a version number that is 
one version greater than the latest version for the file. 


Both files, RICKLIB.OLB and SHEILA.OLB, reside in the 
default directory file on SyY0:. 


8.5.2 Create Switch (/CR) 

Use the Create switch (/CR) to allocate a contiguous library 
file. The switch initializes the library file header, the entry 
point table, and the module name table. 


The /CR switch can be appended only to the output file 
specification. The format for specifying the /CR switch is: 


outfile/CR:size:ept:mnt:libtype:infiletype 


outfi 


/CR 


¢:size 


sept 


smnt 


slibt 


sinfi 
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le 


Specifies the library file being created. The default file 
type is .OLB if an object library is being created, .MLB if 
a macro library is being created, or .ULB if a universal 
library is being created. 


Specifies the Create switch. 


Specifies the new library file size in disk (256 decimal 
word) blocks. The default size is 100 (decimal) blocks. 


Specifies the number of Entry Point Table (EPT) entries to 
allocate. The default value is 512 (decimal) for object 
libraries. This parameter is always forced to zero for 
macro libraries and universal libraries. The maximum number 
of entries is 4096 (decimal). 


Specifies the number of Module Name Table (MNT) entries’ to 
allocate. The default value is 256 (decimal). The maximum 
number of entries is 4096 (decimal). 


ype 


Specifies the type of library to be created. Acceptable 
values are OBJ for object libraries, MAC for macro 
libraries, and UNI for universal libraries. The default is 
the last value specified or implied with the /DF switch (see 
Section 8.5.4), or OBJ if /DF has not been specified. 


letype 
Specifies the default input file type for the created 
universal library. If this value is not specified, the 


default input file type for universal libraries i1is_ .UNI. 
This value is not defined for object or macro libraries. 
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If the values specified for EPT and MNT are not multiples of 64 
(decimal), EPT and MNT are automatically filled out to the next 
disk block boundary. 


Example 


LBR>RICKLIB/CR: :128.:64.:OBJ=SHEILA, LAURA, JENNY 


In this example, a combination of functions is performed. 
First, the library file RICKLIB.OLB is created in the 
default directory on SyY0:. RICKLIB has the following 
attributes: 


size = 100 (decimal) blocks (default size) 
EPT = 128 (decimal) entry points 

MNT = 64 (decimal) module names 

type = .OBJ 


Secondly, object modules from the input files SHEILA.OBJ, 
LAURA.OBJ, and JENNY.OBJ, which reside in the default 
directory on SY0Q:, are inserted into the newly created 
library file. Insert (/IN) is the default switch for input 
files (see Section 8.5.8). 


8.5.3 Delete Switch (/DE) 


Use the Delete switch (/DE) to logically delete library modules 
and their associated entry points (global symbols) from a library 
file. Up to 15 (decimal) library modules and their associated 
entry points can be deleted with one delete command. 


When LBR begins processing the /DE switch, it prints’ the 
following message on the terminal screen: 


MODULES DELETED: 


As modules are logically deleted from the library file, the 
module name is printed on the terminal screen. (See the example 
at the end of this section.) 


If a specified library module is not contained in the library 
file, a message is printed on the terminal screen and the 
processing of the current command is terminated. This message is 
as follows: 


LBR -- *FATAL*-NO MODULE NAMED "name" 


The /DE switch can be appended only to the library file 
specification. 


LBR SWITCHES 


When LBR deletes a module from a library file, the module is not 
physically removed from the file, but is marked for deletion. 
This means that, although the module is no longer accessible, the 
file space it once occupied is not available (unless the deleted 
module was the last one inserted). To physically remove the 
module from the file and make the freed space available, you must 
compress the library (see Section 8.5.1). 
The format for specifying the /DE switch is: 
outfile/DE:modulei1[:module2...:modulen] 


outfile 


Specifies the library file. 


/DE 


Specifies the Delete switch. 


smodule 


Specifies the name of the module to be deleted. 
Example 
LBR>RICKLIB/DE: SHEILA: LAURA: JENNY 
MODULES DELETED: 
SHEILA 
LAURA 
JENNY 
In this example, the modules SHEILA, LAURA, and JENNY and 


their associated entry points are deleted from the latest 
version of library file SY0:RICKLIB.OLB. 


8.5.4 Default Switch (/DF) 


Use the Default switch (/DF) to specify the default library 
file type. Acceptable default values are OBJ for object 
libraries, MAC for macro libraries, and UNI for’ universal 
libraries. 


LBR SWITCHES 


When a default library file type is not specified by the /DF 
Switch, OBJ is the default library file type. 


Specifying a default value: 


1. Sets the default file type for the Create switch (/CR). 


2. Provides a file type default value of .MLB for macro 
libraries, -ULB for universal libraries, and .OLB for 
object libraries when opening an output (library) file. 
Exceptions to this occur when you use /CO or /CR. When 
you specify /CO, the default applies to the library 
input file. When you specify /CR, the default file type 
is .OLB if an object library is being created, .ULB if a 
universal library is being created, or .MLB if a macro 
library is being created. 


The /DF switch only affects the file type of the file to 
be opened. After that, the library header’ record 
information is used to determine the type of Ilibrary 
file being processed. 


The /DF switch can be issued alone or appended to a library file 
specification. The format for specifying the /DF switch is: 


outfile/DF:filetype... 


or 


/DF: filetype 


outfile 


/DF 


Specifies the library file. 


Specifies the Default switch. 


filetype 


Specifies the default library file type: OBJ for object 
library files, MAC for macro library files, and UNI for 
universal library files. 


If a value other than OBJ, ULB, or MAC is specified, the 


current default library type will be set to object libraries 
and the following message will be displayed: 


S=Z0 
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LBR -- *FATAL*-INVALID LIBRARY TYPE SPECIFIED 
Examples 


LBR>/DF : MAC 
LBR>RICKLIB=infile 


The file RICKLIB.MLB is opened for insertion. 


LBR>/DF : MAC 
LBR>RICKLIB/DF:OBJ=infile 


OBJ replaces MAC as the default filetype. The file 
RICKLIB.OLB is opened for insertion. 

LBR>/DF :MAC 

LBR>RICKLIB/CR 


The macro library RICKLIB.MLB is created. 


LBR>/DF:MAC 
LBR>RICKLIB/CR::::OBJ 


Because OBJ 1s specified, it overrides the default (MAC). 
The object library RICKLIB.OLB is created. 


LBR>/DF : OBJ 
LBR>TEMP/CO=RICKLIB.MLB 


Because RICKLIB.MLB is a macro library, MAC overrides’ the 
default (OBJ). The macro library file TEMP.MLB is created 
to receive the compressed output. 


LBR>/DF: UNI 
LBR>RICHLIB=TEST 


The file RICHLIB.ULB is opened for insertion. 


8.5.5 Delete Global Switch (/DG) 


Use the Delete Global switch (/DG) to delete a specified entry 
point (global symbol) from the EPT. Up to 15 (decimal) entry 
points may be deleted with one command. This command does not 
affect the object module that contains the actual symbol 
definition. You may wish to delete an entry point if a module to 
be inserted has the same entry point. 


When LBR begins processing the /DG switch, it prints’ the 
following message on the terminal screen: 
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ENTRY POINTS DELETED: 
As entry points are deleted from the library file, the entry 
point is printed on the terminal screen. (See the example at the 
end of this section.) 
If a specified entry point is not contained in the EPT, a message 
is printed on the terminal screen and the processing of the 
current command is terminated. This message is as follows: 


LBR -- *FATAL* - NO ENTRY POINT NAMED "name" 


The /DG switch can only be appended to the library file 
specification. 


The format for specifying the /DG switch is: 
outfile/DG:globall[:global2...:globaln] 


outfile 


Specifies the library file. 


/DG 


Specifies the Delete Global switch. 


global 


Specifies the name of the entry point to be deleted. 
Example 
LBR>RICKLIB/DG: SHEILA: LAURA: JENNY 
ENTRY POINTS DELETED: 
SHEILA 
LAURA 
JENNY 
In this example, the entry points SHEILA, LAURA, and JENNY 


are deleted from the latest version of the library file 
named SY0:RICKLIB.OLB. 
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8.5.6 Entry Point Switch (/EP) 


Use the Entry Point switch (/EP) to control (include or exclude) 
the placement of global symbols ina library entry point table. 
The switch can be specified in either a positive or negative 
format: 


/EP Include entry points in the entry point table. 

/-EP Do not include entry points in the entry point 
table. 

/NOEP Do not include entry points in the entry point 
table. 


The positive format (/EP) causes all entry points in a module or 
modules to be entered in the library entry point table. 


Either negative format (/-EP or /NOEP) provides for a module to 
be included ina library, but excludes the entry points in that 
module from being entered in the library entry point table. 


/EP is the LBR default. If the switch is not specified, all 
entry points are entered into the library entry point table. 


The /EP switch has no effect on macro or universal libraries. 


The format for specifying the /EP switch is: 


outfile[ /EP J=infile,...infilen 
i[7-BE* | 
[ /NOEP ] 
or 


outfile=infile[ /EP j[,...infilen[/EP ] 
L-yEe- 7 [-/EP ] 
[ /NOEP ] [ /NOEP ] 


outfile 


Specifies the output file. When the entry point switch is 
applied to this file specification, LBR assumes each of the 
input files contains modules for which entry points are _ to 
be either included or excluded. 
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infile 


Specifies an input file. When the /EP switch is applied to 
an input file specification, LBR assumes only the input 
files to which the switch is applied contain modules’ for 
which entry points are to be either included or excluded. 


NOTE 


Although not reflected in the command formats, 
the positive and negative forms of the switch may 
be applied to both the output and input file 
Specifications. For example, the effect of /EP 
applied to the output file can be overridden by 
applying /-EP to a specific input file. 


The /-EP switch is useful for including modules that contain 
duplicate entry point names in the same library. The /-EP switch 
provides the means for entering a module in the library without 
having its entry points included in the library entry point 
table. 


The /-EP switch is also useful in the case where the Task Builder 
uses only module names to search for modules in an object module 
library. In this case, entries in the library entry point table 
are not required. The /-EP switch can be used to exclude entry 
points from being entered in the library entry point table. 


Depending on whether the /EP switch is applied to the output 
Specification or to an input specification, it has either a 
global or local effect. 


When applied to the output file specification, the /EP switch has 
a global effect. That is, LBR either includes all entry points 
in the entry point table or excludes all entry points from being 
entered in the entry point table. 


When applied to an input file specification, the Entry Point 
Switch has a local effect. That is, LBR either includes entry 
points in the entry point table, or excludes entries from being 
entered in the entry point table for only those modules to which 
the switch is applied. 


Entry points in an object module are not affected by the /EP 
Switch. The switch only affects entries in the library entry 
point table. 
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8.5.7 Extract Switch (/EX) 


Use the Extract switch (/EX) to extract (read) one or more 
modules from an object or macro library file and write them into 
a specified output file. If more than one module is extracted, 
the modules are concatenated in the output file. The extract 
operation has no effect on the library file from which the 
modules are extracted; that file remains intact. Up to eight 
modules may be specified in one extract operation for object and 
macro libraries. However, only one module may be specified in 
one extract operation for a universal library. 


For object and macro libraries, if no modules are specified in 
the command line, all modules in the library are extracted and 
concatenated in the output file in alphabetical order. 


For universal libraries, RMS fields cannot be extracted to a 
record-oriented device, such as a terminal. 


The /EX switch may be applied only to input file specifications. 
The format for specifying the /EX switch is: 


outfile=infile/EX[:modulename1...:modulenamen|] 


outfile 


Specifies the file into which extracted modules are to _ be 
stored. The default file type for this file is .OBJ if the 
input modules are object modules. The default file type is 
.MAC if the input modules are macro modules. If the library 
is a universal library, the outfile retains the infile type 
of the module extracted. (However, you are allowed to 
extract only one universal library module at a time.) 


infile 
Specifies the library file from which the modules are to be 
extracted. The default file type is .ULB, .OLB, or .MLB, 


depending on the current default library type. 


JEX 


Specifies the Extract switch. 
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modulename 


Specifies the name of the module to be extracted from the 
library. 


Examples 
LBR>DRIVERS=RSX11M/EX:DXDRV: DKDRV: TTDRV 


The object modules DXDRV, DKDRV, and TTDRV are concatenated 
in alphabetical order and written into the file DRIVERS.OBJ. 


LBR>TI:={1,5]RSXMAC.SML/EX:QIOSS 
The macro QIOSS is written to the terminal screen. 
LBROTEST.OBS=TEST/EX 


All of the modules in the library TEST.OLB are written into 
the file TEST.OBS in alphabetical order. 


8.5.8 Insert Switch (/IN) for Object and Macro Libraries 


Use the Insert switch (/IN) to insert modules into a library 
file. Any number of input files can be specified. For object 
and macro libraries, each input file can contain any number of 
concatenated input modules. For macro libraries, only 
first-level macro definitions are extracted from the input files. 
All text outside of the first-level macro definitions is ignored. 
(The Insert switch for Universal Libraries, is explained in 
Section 8.5.9.) The /IN switch is the default library file option 
and can be appended only to the library file specification. 


If you attempt to insert an input module that already exists in 
the library file, the following message is printed on the 
terminal screen: 


LBR -- *FATAL* DUPLICATE MODULE NAME "name" IN filename 
Likewise, if you attempt to insert a module and a module contains 
an entry point that duplicates one that is already in the EPT, 


the following message is printed on the terminal screen: 


LBR -- *FATAL* DUPLICATE ENTRY POINT "name" IN filename 
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The format for specifying the /IN switch is: 


outfile[/IN]J=infile1l[(,infile2,...infilen] 


outfile 


Specifies the library file into which the input modules are 
to be inserted. The default file type depends on the 
current default (see Section 8.5.4). It is .OLB if the 
current default is object libraries, .MLB if the current 
default is macro libraries. 


/IN 
Specifies the Insert switch. 

infile 
Specifies the input file containing the modules to _ be 
inserted into the library file. The default file type is 
OBJ 1f the outfile is an object library and .MAC if the 
outfile is a macro library. 

Example 


LBR>RICKLIB/IN=SHEILA, LAURA, JENNY 


In this example, the modules contained in the latest 
versions SHEILA, LAURA, and JENNY, which reside in the 
default directory on SY0:, are inserted into the latest 
version of the library file RICKLIB, which also resides in 
the default directory on SyY0:. The default file type for 
SHEILA, LAURA, and JENNY is .OBJ if RICKLIB is an object 
module library, or .MAC if RICKLIB is a macro library. 


8.5.9 Insert Switch (/IN) for Universal Libraries 


The Insert switch (/IN) works basically the same for universal 
libraries as it does for object and macro libraries. However, 
when inserting a file into a universal library, the /IN switch is 
applied to the input file rather than the output file. You can 
also specify module name and descriptive information as _ switch 
values in the command line. In addition, LBR copies input file 
attributes to the module header. 
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The high block indicator (F.HIBK of the file’s descriptor block) 
and the end of file indicator (F.EFBK of the file’s FDB) are 
included in the input file’s user file attributes. LBR makes the 
high block indicator equal to the end of file indicator in the 
module header. This means that when a module is extracted to a 
file, that file will have as many blocks allocated to it as are 
used. 


The format for specifying the /IN switch for universal libraries 
1S: 


outfile=infile/IN:name:op:op:op:op 

outfile 
Specifies the universal library into which the infile is to 
be inserted. 

infile 


Specifies the input file to be inserted into the outfile. 
The default for the file type is the value indicated at the 


universal library’s creation time. See Section 8.5.2. 

/IN 
Specifies the Insert switch. 

sname 
Optionally specifies the module name (up to six Radix-50 
characters). The default is the first six characters of the 
input file name. 

sop 
Specifies optional descriptive information (up to Six 
Radix-50 characters) to be stored in the module header. The 
default is null. If only part of the information set is 
specified, all preceding colons must be supplied. 

Example 


LBR>RICKLIB.ULB=JOE.TXT/IN:MOD1: THIS: IS: JAN2: TEXT 
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In this example, LBR inserts JOE.TXT into the universal 
library RICKLIB.ULB as MOD1. "THIS", "IS", "JAN2", and 
"TEXT" are stored in the module header. 


You can insert JOE.TXT without the /IN switch and its 
values. As a result, all the information normally specified 
by the switch values defaults as described in this example. 


8.5.10 List Switches (/LI, /LE, /FU) 


Use the list switches to produce a printed listing of the 
contents of a library file. Three switches allow you to select 
the type of listing desired. These switches are as follows: | 


Jul Produces a listing of the names of all modules in 
the library file. 


/LE Produces a listing of the names of all modules in 
the library file and their corresponding entry 
points. 

/FEU Produces a listing of the names of all modules in 
the library file and gives a full module 
description for each: that is, size, date of 


insertion, and module-dependent information. 


These switches can be appended only to the output file 
Specification or the list file specification. 


The /LI switch is the default value. It need not be specified 
when a listing file has been specified or when any other list 
Switch is included in the command line. 

The format for specifying list switches 1s: 


outfile([,listfile]/switch(es) 


outfile 


Specifies the library file whose contents are to be listed. 


listfile 


Optionally specifies the listing file. If not specified, 
the listing is directed to the terminal screen. 
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/switch(es) 


Specifies the list option(s) selected. 
Examples 
LBR>RICKLIB/LI 


In this example, a listing of the names of all the modules 
contained in file SYQ:RICKLIB.OLB is printed on the terminal 
screen. 


LBR>RICKLIB/LE 

In this example, a listing of the names of all the modules 
and their entry points (contained in file SY0:RICKLIB.OLB) 
1S printed on the terminal screen. 

LBR>RICKLIB/FU 

In this example, a listing of the names of all the modules 
in file SYO:RICKLIB.OLB, and a full description of each one 
contained is printed on the terminal screen. 

LBR>DW1: [ FOOBAR]RICKLIB,LP.LST/LE/FU 

In this example, LBR creates file LP.LST in directory 
[FOOBAR] on DW1i, which lists the module names, their entry 


points, and a full description of each module for file 
RICKLIB. 


8.5.11 Modify Header Switch (/MH) 

The Modify Header switch (/MH) pertains only to universal 

libraries and allows you to modify the optional user-specified 

information in the module header. 

The format for specifying the /MH switch is: 
outfile/MH:module:op:op:op:op 

outfile 


Specifies an output file for the universal library. The 
file type defaults to .ULB. 
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/MH 
Specifies the Modify Header switch. 

smodule 
Specifies the name of the module whose descriptive 
information is to be modified. 

sop 
Specifies the optional user information (up to six Radix-50 
characters) to be stored in the module header. The default 
is null and indicates that the corresponding information 
field is not to be changed. Also, entering a pound sign (#) 
clears the corresponding information field. 

Example 


The optional descriptive information for module A of 
RICKLIB.ULB is: 


"MODA" "FCHCD" TOR" "EPCcH" 
The LBR command is: 
LBR>RICKLIB/MH:A:FCHTS:#:: 


The optional descriptive information for module A in file 
RICKLIB is changed to: 


"FCHTS" 8 ve "OF" " FCH" 


8.5.12 Replace Switch (/RP) For Macro and Object Libraries 


Use the Replace switch (/RP) to replace modules ina library file 
with input modules of the same name. Any number of input files 
are allowed and each file can contain any number of concatenated 
input modules. 


For macro libraries, only first-level macro definitions are 
extracted from the replacement files. 


When a match occurs on a module name, the existing module is 
logically deleted and its entries are removed from the EPT. 
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As each module in the library file is replaced, a message is 
printed on the terminal screen. This message, which contains the 
name of the module being replaced, is as follows: 


MODULE "name" REPLACED 


If the module to be replaced does not exist in the library file, 
LBR assumes that the input module is to be inserted and 
automatically inserts it without printing a message. 


The /RP switch can be specified in either of the following 
formats: 


e Global format - The /RP switch is appended to the library 
file specification and all of the input files are assumed 
to contain replacement modules. 


@e Local format - The /RP switch is appended to an input 
file specification and only the file to which the /RP 


Switch is appended is considered to contain replacement 
modules. 


Global Format 
outfile/RP=infilel[,infile2z,...infilen] 

outfile 
Specifies the library file. The default file type depends 
on the current default (see Section 8.5.4). It is .OLB if 


the current default is object libraries or .MLB if the 
current default is macro libraries. 


Specifies the Replace switch. 

infile 
Specifies the input file that contains replacement modules 
for the library file. The default type is .OBJ if outfile 


is an object library or .MAC if it is a macro library. 


The Global format allows you to specify a list of input files 
without having to append the /RP switch to each of them. 
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To override the global function for a particular input file (that 
is, to instruct LBR to process a particular file in a list as a 
file containing modules to be inserted but not replaced), append 
/-~RP or /NORP to the desired input file specification. 


Local Format 
outfile=infilel[/RP][,infile2[/RP],...infilen[/RP] ] 
outfile 
Specifies the library file. The local format default is the 
same as the global format default. 
infile 
Specifies the input file that contains replacement modules 


for the output library file. The local format default is 
the same as the global format default. 


/RP 
Specifies the Replace switch. Appending the /RP switch to 
an input file specifier constitutes the local format of the 
Switch. This overrides the LBR default (/IN) and instructs 
LBR to treat the module(s) contained in the specified file 
as replacement modules. 

Examples 


The files used in the following four examples, and _ the 
modules contained within each file, are depicted in Figure 
8-8. These files are assumed to reside in the default 
directory on the default device and the initial state of the 
library file is assumed to be as shown in Figure 8-8. 


1. LBR>RICKLIB/RP=SHEILA, LAURA, JENNY 
MODULE "SHEILA" REPLACED 
MODULE "LAURA1" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE "JENNY1" REPLACED 
MODULE "JENNY2" REPLACED 
This example uses the global format for the /RP switch. 


Object modules from the input files SHEILA, LAURA, and 
JENNY replace modules by the same names in the library 
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file RICKLIB, and modules JENNY3 and LAURA3 are 
inserted. Figure 8-9 shows the resulting library file. 
LBR>RICKLIB=CHRIS,SHEILA/RP 
MODULE "SHEILA" REPLACED 


In this example, the local format of the /RP switch is 


used. The object module SHEILA from file SHEILA is 
replaced in the library file RICKLIB. The object 
modules in the file CHRIS are inserted in the library 
file. (See the description of the /IN switch in Section 


8.5.8) The resulting library file is shown in Figure 
8-10. 


LBR>RICKLIB/RP=SHEILA, LAURA, JENNY, CHRIS/-RP 


MODULE "SHEILA" REPLACED 
MODULE "LAURA1" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE "JENNY1" REPLACED 
MODULE "JENNY2" REPLACED 


In this example, the /-RP switch is used to override the 
global format of the command. Object modules in files 
SHEILA, LAURA, and JENNY are processed as modules to be 
replaced, and file CHRIS is processed as a file that 
contains modules to be inserted. The resulting library 
file is shown in Figure 8-11. 


LBR>RICKLIB/RP=SHEILA, LAURA/-RP, JENNY 


MODULE "SHEILA" REPLACED 
LBR -- *FATAL* -- DUPLICATE MODULE "LAURA1" IN 


LAURA.OBJ;1 


In this example, only module SHEILA from file SHEILA was 
replaced. The user specified that the modules in file 
LAURA not be replaced (/-RP), but inserted. One of the 
modules contained in file LAURA duplicated an already 
existing module in file RICKLIB. Therefore, LBR issued 
the fatal error message and terminated the processing of 
the current command line. 


LBR SWITCHES 


OUTPUT 
LIBRARY FILES 


FILE NAME|RICKLIB.OLB;1|SHEILA.OBJ;1 


JENNY] 


SHEILA 


OBJECT 


JENNY 2 


MODULES 


LAURA] 
LAURA2 
SHEILA 


INPUT FILES 


LAURA.OBJ;1! JENNY.OBJ;:1| CHRIS.OBJ;1 


CHRIS1 
CHRIS2 
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LAURAI JENNY] 


LAU RA2 JENNY 2 


LAURA3 JENNY3 


Figure 8-8: Sample Files Used in LBR Examples 1-4 
RICKLIB.OLB;1 
JENNY1 
JENNY 2 
SENNY3? 
LAURAIL 
LAURA2 
LAURA3* 
SHEILA 
1. These modules did not exist in the 
library file prior to the execution of 
this example, but they did exist in the 
InpuT. wibes:, LBR, therefore, assumed 
that they were to be inserted. Since 
LBR handled these modules as a normal 
insert, no message waS printed on the 
input terminal. 
ZK-192-81 
Figure 8-9: Output Library File After Execution of Example 1 
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RICKLIB.OLB:1 | 


CHRIS1? 


CHRIS2+ 


ri MRI a 


JENNY1 | 
JENNY 2 ! 
LAURA1 | 


LAURA2 
2 


SHEILA 


1. These modules are inserted. 


2. This module is replaced. 
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Figure 8-10: Output Library File After Execution of Example 2 


RICKLIB.OUB. 1] 
1 


CHRIS] 
CHRIS2? 
JENNY] 
JENNY 2 
JENNY 3° 
LAURA] 

“{RURAZ 

LAURA3“ 


SHEILA 


pee | 


1. These modules were specified to be 
inserted. Had a module of the same name 
been present, a fatal error message 
would have been issued. See Example 4. 


2. These modules were inserted bydefault. 
ZK-194-8) 


Figure 8-11: Output Library File After Execution of Example 3 
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8.5.13 Replace Switch (/RP) for Universal Libraries 
Use the /RP switch for universal libraries in the same way as for 
macro and object libraries. However, you can also specify the 
same values for the /RP switch as for the /IN switch for 
universal libraries. See Section 8.5.9. 
As with macro and object libraries, you can specify the /RP 
Switch with either the output file specification or with the 
input file specifications. 
The global format of the /RP switch for universal libraries is: 
outfile/RP:name:op:op:op:op=infile[,infile2,....infilen] 
The local format of the /RP switch for universal libraries is: 
outfile=infile/RP:name:op:op:op:op[,infile2....infilen] 
outfile 
Specifies the universal library file. 
infile 
Specifies the input file that contains replacement modules 
for the library file. The default for the file type is the 


value indicated at the universal library’s creation time. 
See Section 8.5.2. 


/RP 
Specifies the Replace switch. 

sname 
Optionally specifies the module name to be replaced (up _ to 
Six Radix-50 characters). The default is the first six 
characters of the infile name. 

sop 
Specifies optional descriptive information (up to S1x 
Radix-50 characters) to be stored in the module header. The 
default is null. If only part of the information set 15s 
specified, all preceding colons must be supplied. 

Example 


LBR>TEXT.ULB=DEBBIE.TXT/RP: : THIS: IS: JAN3: UPDATE 


MODULE "DEBBIE" REPLACED 
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In this example, LBR replaces the module DEBBIE in the 
universal library TEXT.ULB with an updated module from file 
DEBBIE.TXT. The date of replacement is specified by the 
optional user information and inserted in the module header. 


Note that the optional name is omitted. 


The initial state of the library file is shown in Figure 
8-12. The resulting library file is shown in Figure 8-13. 


OUTPUT 
LIBRARY FILE INPUT FILES 


FILE NAME TEXTS ULB e4 DEBBIE.TXT 
MODULES DEBBIE 
BERNIE 


ZK-195-81 


Figure 8-12: Sample Files for Universal Library Replace Example 


TEXTZ UCB} 2 


DEBBIE? 


BERNIE 


1.The module DEBBIE was replaced. If <a 
different infile were specified, that 
file would become module DEBBIE and 


occupy the same location in TEXT.ULB. 
ZK.196-61 


Figure 8-13: Output Library File After Library Replace 
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8.5.14 Selective Search Switch (/SS) 


Use the Selective Search switch (/SS) to set the selective search 
attribute bit in the module header of object modules as they are 
inserted into an object library. The switch has no effect when 
applied to modules being inserted into a macro library. The 
Switch may be specified with input files for insertion or 
replacement operations only, and it affects all modules in the 
input file to which it is applied. 


Object modules with the selective search attribute are given 
Special treatment by the Task Builder. Global symbols, defined 
in modules with the selective search attribute, are only included 
in the Task Builder’s symbol table if they are previously 
referenced by other modules. Thus, only referenced symbols will 
be listed with the module in the Task Builder memory allocation 
file, thereby reducing task build time. The /SS switch should 
only be applied to object files whose modules contain only 
absolute (not relocatable) symbol definitions. 

The format for specifying the /SS switch is: 

outfile=infilei/SS[,infile2[/SS],...infilen[/SS] ] 


outfile 


Specifies the library file. 

infile 
Specifies the input file that contains modules to _ be 
selectively searched. 
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Specifies the Selective Search switch. 
Example 
LBR>ANGEL=JOHN, JILL/SS,MARK/SS , MARY 
The object files JOHN.OBJ, JILL.OBJ, MARK.OBJ, and MARY.OBJ 
are inserted into object library ANGEL.OLB. The selective 


search attribute bit is set in both the JILL and MARK object 
module header. 
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8.5.15 Squeeze Switch (/SZ) 


Use the Squeeze switch (/SZ) to reduce the size of macro 
definitions by eliminating all trailing blanks and tabs, blank 
lines, and comments from macro text. The /SZ switch is used to 
conserve memory in the MACRO-11 Assembler and to reduce the size 
of macro library files. The /SZ switch has no effect on object 
libraries or universal libraries. 


The /SZ switch can be specified in either of two formats: 

@e Global format - The /SZ switch is appended to the library 
File specification. All of the input files are assumed 
to contain modules to be squeezed. 

@ Local format - The /SZ switch is appended to an input 
file specification. The /SZ switch works only on the 
file to which you append it. 

Global Format 
outfile/SZ=infilei[,infile2,...infilen] 


outfile 


Specifies the library file. 
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Specifies the Squeeze switch. 


infile 


Specifies the input file that contains modules to _ be 
squeezed during insertion into the library file. 


Use the global format of the /SZ switch to specify a list of 
input files without having to append the /SZ switch to each of 
them. To override the global function for a particular input 
file (that is, to instruct LBR to process a particular file ina 
list as a file containing modules to be inserted but not 
squeezed), append /-SZ or /NOSZ to the desired input file 
specification. 


Local Format 


outfile=infilei/SZ[,infile2[/SZ]...,infilen[/S2] ] 
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outfile 


Specifies the library file. 

infile 
Specifies the file that contains modules to be squeezed 
during insertion into the library file. 


/S2 


Specifies the Squeeze switch. 


LBR uses the following algorithm on each line to be squeezed and 
then inserts the resulting line into the library file: 


1. The line is examined for the rightmost semicolon (;). 


2. If a semicolon is located, it is deleted, along with all 
trailing characters in the line. 


3. All trailing blanks and tabs in the line are deleted. 


4, If the resulting line is null, nothing is transferred to 
the library file. 


If the line contains a semicolon embedded in noncomment text and 
you want comments squeezed, code a dummy comment for that line. 
The /SZ switch will use only the rightmost comment during squeeze 
processing. 


Example 


Figure 8-14 illustrates the use of the LBR /SZ switch. A 
file containing input text to be squeezed is illustrated, 
along with the text actually inserted into the library file 
after the squeeze operation has been completed. 


LBR SWITCHES 


BEFORE 
~MACRO MOVSTR RX,RY,?LBL 


= <= NOTE. is ; 
BOTH ARGUMENTS MUST BE REGISTERS ; 


MOVB (RA) +,-CRY) + ;MOVE A CHARACTER 
BNE LBL ;CONTINUE UNTIL NULL SEEN 
DEC RY ;BACKUP OUTPUT PTR TO NULL 


MOVSTR 
- ENDM 


AFTER 


-MACRO MOVSTR RX,RY,?LBL 

- - NOTE : 

BOTH ARGUMENTS MUST BE REGISTERS 
MOVB (RX)+, (RY) + 

BNE LBL 

DEC RY 

- ENDM 


ZK-197-81 


Figure 8-14: MACRO Listing Before and After Running LBR with /SZ 


8.6 COMBINING LIBRARY FUNCTIONS 


Two or more library functions may be requested in the same 
command line. The only exceptions are that /CO cannot be 
requested with anything else except /LI, and /CR and /DE cannot 
be specified in the same command line. 


Functions are performed in the following order: 


1. Default switch (/DF) 

2. Create switch (/CR) 

3. Delete switch (/DE) 

4. Delete Global switch (/DG) 

5S. Modify Header switch (/MH) 

6. Insert (/IN), Replace (/RP), Selective Search (/SS), 
Squeeze (/SZ), Entry Point (/EP) switches 

7. Compress switch (/CO) 

8. Extract switch (/EX) 

9. List switches (/LI), /LE, /FU) 


COMBINING LIBRARY FUNCTIONS 


Example 
LBR>FILE/DE:XYZ:SA,FILE.LST: /LE/FU=MODX, MODY/RP 
Functions, performed in order, are: 

1. Delete modules XYZ and SA. 


2. Insert all modules from MODX and replace duplicate 
modules of MODY. 


3. Produce a listing of the resultant library File on 


the line printer with full module descriptions and 
all entry points. 


8.7 LBR ERROR MESSAGES 


LBR returns two types of error messages: diagnostic and fatal. 
Diagnostic error messages describe a condition that requires 
consideration, but the nature of the condition does not warrant 
termination of the command. Diagnostic messages are issued to 
your terminal screen in the format: 

LBR -- *DIAG* - message 
Fatal error messages describe a condition that caused LBR_ to 
terminate the processing of a command. When this occurs, LBR 
returns to the highest level of command input. For example, LBR 
issues the fatal error message and exits if you enter the 
command: 

S RUN SLBR/COMMAND:"LBR cmd" 


where cmd is an LBR command. 


If, however, you enter the command in response to the LBR prompt, 
that is, 


LBR>cmd 
LBR issues the fatal error message and reprompts. 


Fatal error messages are issued to your terminal screen in the 
format: 


LBR ERROR MESSAGES 


LBR -- *FATAL* - message 


If a fatal error occurs during the processing of an indirect 
command file, the command file is closed, the fatal error 
message--followed by the command line in error---is issued to 
your terminal screen and LBR- returns to the highest level of 
command input. 


8.7.1 Effect of Fatal Errors on Library Files 
The status of a library file after fatal errors is: 


1. In general, output errors leave the library in an 
indeterminate state. 


2. During the deletion process, the library is rewritten 
prior ste, the printing of the individual 
module-/entry-point-deleted messages. 


3. jDuring the replacement process, the library is rewritten 
prior to the printing of the individual module-replaced 
messages. 


4. During the insertion process, the library is rewritten 


after the insertion of all modules in each individual 
input file, that is, between input files. 


8.7.2 LBR Error Messages 


LBR -- BAD LIBRARY HEADER 


Explanation: The file is not a library file or it is 
corrupted. 


User Actions 


e If the file is not a library file, reenter the command 
line with a proper library file specified. 


e If the file is a proper library file, the volume may be 
corrupted. 


€ If the volume is corrupted, it must be reconstructed 
before it can be used. 


LBR ERROR MESSAGES 


LBR -- CANNOT MODIFY HEADER 


Explanations An attempt was made to modify the module 
header of a module in an object library or macro library. 
No change is made to the module header. 


User Actions Reenter the command line, specifying a module 
in a universal library. 


LBR -- COMMAND I/O ERROR 
Explanation: One of the following conditions may exist: 
® A problem exists on the physical device. 


@ The file is corrupted or the format is incorrect (for 
example, record length exceeds 132 bytes). 


User Actions Determine which of the conditions caused the 


message and correct that condition. Reenter the command 
line. 


LBR -- COMMAND SYNTAX ERROR 
command line 


Explanation: A command was entered in a format that does 
not conform to syntax rules. 


User Actions: Reenter the command line, using the correct 
syntax. 


LBR -- DUPLICATE ENTRY POINT NAME "name" IN filename 


Explanations An attempt was made to insert a module into a 
library file when both contain an identically named entry 
point. 


User Action: Determine if the specified input file is the 
correct file. If not, reenter the command line, specifying 
the correct input file. If the input file is the correct 
file, you can delete the duplicate entry point from the 
library and reenter the command line. 
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LBR -- DUPLICATE MODULE NAME "name" IN filename 


Explanation: An attempt was made to insert (without 
replacing) a module into a library that already contains a 
module with the specified name. 


User Actions: Determine if the specified input file is the 
correct file. If the input file is correct, decide whether 
to delete the duplicate module from the library file and 
insert the new one, or replace the duplicate module with the 
/RP switch appended to the input file specification. 


LBR -- EPT OR MNT EXCEEDED IN filename 


Explanations The EPT or MNT table limit was reached during 
the execution of an insert or replace operation. 


User Action: Copy the library, increasing the table space 
by means of the Compress switch. Reenter the command line. 


LBR -- EPT OR MNT SPACE EXCEEDED IN COMPRESS 


Explanation: An EPT or MNT table size was specified for the 
output library file that is not large enough to contain the 
EPT or MNT entries used in the input library file. 


User Actions Reenter the command line with a larger EPT or 
MNT table size specified. 


LBR -- ERROR IN LIBRARY TABLES, FILE filename 


Explanations The library file is corrupted or 1s not a 
library file. 


User Action: If the file is corrupted, no recovery is 
possible; the file must be reconstructed. If the file is 
not a library file, reenter the command line with the 
correct library file specified. 


LBR -- EXACTLY ONE INPUT FILE MUST APPEAR WITH /CO 


Explanations No input library file, or more than one file, 
was specified when using the /CO switch. 


User Actions Reenter the command line with only one input 
file specified. 
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LBR -- FATAL COMPRESS ERROR 


Explanation: The input library file is corrupted or is not 
a library file. 


User Actions: No recovery is possible. The file in question 
must be reconstructed. 


LBR -- GET TIME FAILED 


Explanation: This error occurs when LBR attempts to execute 
a Get Time Parameters directive and fails. The error is 
caused by a system malfunction. 


User Action: Reenter the command line. If the problem 
persists, call your DIGITAL Customer Support Center. 


LBR -- ILLEGAL DEVICE/VOLUME 
command line 


Explanation: The Device specifier entered does not conform 
to syntax rules. A device specifier consists of two ASCII 
characters, followed by one or two optional octal digits. 


User Actions Reenter the command line with the correct 
device syntax specified and followed by a colon. 


LBR -- ILLEGAL DIRECTORY 
command line 


Explanation: The directory entered does not conform to 
Syntax rules. Directory syntax consists of a left square 
bracket, followed by one to nine alphanumeric characters (or 
one to three octal digits, a comma, and one to three octal 
digits), terminated by a right square bracket (for example, 
[USERFILES]). 


User Action: Reenter the command line with the correct 
directory syntax. 

LBR -- ILLEGAL FILENAME 

command line 


Explanation: One of the following was entered: 


® A file specifier that contains a wildcard. 
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® A file specifier that contains neither a file name nor a 
file type. 


User Actions: Reenter the command line correctly. 


LBR -- ILLEGAL GET COMMAND LINE ERROR CODE 
Explanation: LBR could not process the command line. 


User Actions Reenter the command line. If the problem 
persists, call your DIGITAL Customer Support Center. 


LBR -- ILLEGAL SWITCH 
command line 


Explanations: A non-LBR switch was specified or ae legal 
Switch was specified in an invalid context. 


User Actions Reenter the command line with the correct 
Switch specification. 


LBR -- ILLEGAL SWITCH COMBINATION 


Explanation: Switches were entered that cannot be executed 
in combination. See Section 8.6. 


User Action: Reenter the command line, specifying the 
Switches in the proper combination. 


LBR -- INDIRECT COMMAND SYNTAX ERROR 
command line 


Explanations An indirect command file was specified in a 
format that does not conform to syntax rules. 


User Action: Reenter the command line with the correct 
syntax. 


LBR -- INDIRECT FILE DEPTH EXCEEDED 
command line 


Explanation: An attempt was made to exceed one level of 
indirect command files. 


User Actions Rerun the job with only one level of indirect 
command file specified. 


LBR ERROR MESSAGES 

LBR -- INDIRECT FILE OPEN FAILURE 

command line 
Explanation: The requested indirect command file does not 
exist as specified. One of the following conditions may 
exist: 
e The user directory area is protected against access. 
® A problem exists on the physical device. 
® The volume is not mounted. 
2 The specified file directory does not exist. 
® The file does not exist as specified. 
® Insufficient dynamic memory exists in the Executive. 
User Action: Determine which of the conditions caused _ the 
message and correct that condition. Reenter the command 
line. 


LBR -- INPUT ERROR ON filename 


Explanation: The file system, while attempting to process 
an input file, has detected an error. 


A problem exists with the physical device. 


User Actions: Reenter the command line. 


LBR -- INSUFFICIENT DYNAMIC MEMORY TO CONTINUE 


Explanation: Your library is too large for the attempted 
operation. 


User Actions Break up the library into two or three smaller 
libraries. 
LBR -- INVALID EPT AND/OR MNT SPECIFICATION 


Explanations: An EPT or MNT value greater’ than 4096 
(decimal) was entered in a /CR or /CO switch. 


User Action: Reenter the command line with the correct 
value specified. 
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LBR -- INVALID FORMAT, INPUT FILE filename 


Explanations The format of the specified input file is not 
the standard format for a macro source or object file, or 
the input file is corrupted. 


User Actions Reenter the command line with the correct 
input file specified. 


LBR -- INVALID LIBRARY TYPE SPECIFIED 


Explanations An invalid library type was specified when 
uSing the Create or Default switch. The values OBJ, MAC, 
and UNI are the only valid specifications. See Sections 
Teoge. and 1.564% 


User Actions Reenter the command line with OBJ, MAC, or UNI 
specified. 


LBR -- INVALID MODULE FORMAT in insertion module 


Explanations An attempt was made to insert a macro module 
into an object library. 


User Actions Determine if an object file was to be inserted 
into an object library. If so, reenter the command line 
with the correct object file. If a macro library was to 
receive the insertion, reenter the command line with the 
correct macro library. 


LBR -- INVALID NAME -- "name" 


Explanations A module name that contains a non-Radix-50 
character was specified for deletion, insertion, or 
replacement of a module ina universal library or in a macro 
module; or a module name was specified for modification of a 
universal module header. Radix-50 characters consist of the 
letters A through Z, the numbers OQ through 9, and the 
special characters period (.) and dollar sign (S$). 


User Actions: Reenter the command line with a valid name. 
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LBR -- INVALID OPERATION FOR OBJECT AND MACRO LIBRARIES 
Explanation: Module header information was supplied for an 
object library or macro library in an insert or replace 


operation. 


User Action: No action required. The command will be 
executed as if the information had not been supplied. 


LBR -- INVALID RAD50 CHARACTER IN "character string" 
Explanation: A character supplied as part of information 
when using the Insert, Replace, or Modify Header switches 
for a universal library is not a Radix-50 character. 
User Actions Determine which character of the corresponding 
Switch value is not a Radix-50 character. Reenter a 
Radix-50 character in place of the invalid character. 


LBR -- I/O ERROR ON INPUT FILE filename 


Explanation: A read error has occurred on an input file. 
One of the following conditions may exist: 


a A problem exists on the physical device. 


8 The file is corrupted or the format is wrong (record 
length exceeds 132 bytes). 


User Action: Determine which of the conditions caused _ the 
message and correct that condition. Reenter the command 
line. 


LBR -- LIBRARY FILE SPECIFICATION MISSING 


Explanation: A command line was entered without specifying 
the library file. 


User Action: Reenter the command line with the library file 


specified. 
LBR -- MARK FOR DELETE FAILURE ON LBR WORK FILE 
Explanations: When LBR begins processing commands, it 


automatically creates a work file and marks it for delete. 
For some reason, this marking for delete failed. 
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The work file constitutes a lost file because it does not 
appear in any file directory. 


User Actions The file may be deleted by typing the 
following command from the DCL command level: 


S$ @VERIFY 
LBR -- MULTIPLE MODULE EXTRACTIONS NOT PERMITTED FOR UNI MODULES 
Explanations: An attempt was made to extract more than _ one 
module from a universal library. The first module specified 


1s extracted, but others are ignored. 


User Action: Reenter the command line for each additional 
extraction. 


LBR -- NO ENTRY POINT NAMED "name" 


Explanation: The entry point to be deleted is not in the 
specified library file. 


User Actions Determine if the entry point is misspelled or 
if the wrong library file is specified. Reenter the command 
line with the entry point or the library file correctly 
specified. 


- LBR -- NO MODULE NAMED "module" 


Explanations The module to be deleted is not in the 
specified library file. 


User Action: Determine if the module name is misspelled or 
if the wrong library file is specified. Reenter the command 
line with the module name correctly specified. 

LBR -- OPEN FAILURE ON FILE filename 
Explanation: The file system, while attempting to open a 
file, has detected an error. One of the following 


conditions may exist: 


e The user directory area is protected against an open 
operation. 


6 A problem exists on the physical device. 
é The volume is not mounted. 


& The specified file directory does not exist. 
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The file does not exist as specified. 


Insufficient contiguous space to allocate the library 
file (Compress and Create only). 


Insufficient dynamic memory exists in the Executive. 


User Actions Determine which of the above conditions caused 


the 


message and correct that condition. Reenter’ that 


command line. 


LBR -- OPEN FAILURE ON LBR WORK FILE 


Explanation: The file system, while attempting to open the 
LBR work file, has detected an error. The LBR work file is 
created on the volume from which LBR was installed. One of 
the following conditions may exist: 


The volume is full. 
The device is write-protected. 
A problem exists with the physical device. 


Insufficient dynamic memory exists in the Executive. 


User Actions Determine which of the conditions caused the 
message and correct that condition. Reenter the command 
line. 


LBR -- OUTPUT ERROR ON filename 


Explanation: A write error has occurred on the output file. 
One of the following conditions may exist: 


The volume is full. 
The device is write-protected. 


The hardware has failed. 


User Actions If the volume is full, delete all unnecessary 


files and rerun LBR. If the device is write-protected, 
write-enable the device and reenter the command line. If 
the hardware has failed, swap devices and reenter the 


command line or wait until the device is repaired and rerun 


LBR. 
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LBR -- POSITIONING ERROR ON filename 


Explanation: A positioning error has occurred on the input 
file. One of the following conditions exist: 


e A problem exists on the physical device. 

e The file is corrupted or the format is wrong. 
User Actions Determine which of the conditions caused _ the 
message and correct that condition. Reenter the command 
line. 

LBR -- RMS MODULES CANNOT BE EXTRACTED TO RECORD ORIENTED DEVICES 

Explanation: An attempt was made to extract a module 
inserted from a nonsequential RMS file to a record-oriented 


device. This is a fatal error message. 


User Actions Extract the file to a disk and then use an RMS 
conversion to make an RMS sequential file. 


LBR -- TOO MANY OUTPUT FILES SPECIFIED 


Explanation: More than two output files were specified. 
LBR makes the following assumptions: 


@ The first output file specified is the output library 
file. 


© The second output file specified is the listing file. 


é The third through n files specified to the left of the 
equal sign are ignored. 


User Actions No action is required. LBR continues as 
though the extra file(s) had not been specified. 


LBR -- VIRTUAL STORAGE REQUIREMENT EXCEEDS 65536 WORDS 


Explanation: This error may occur if you are working with 
maximum size libraries. You might have specified a single 
command line that first logically deletes a large number of 
modules and entry points, then replaces them with an equally 


large number of modules and entry points. The replacement 
modules and entry points have names much different from 
those being replaced. This message usually indicates a 
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system error. 

User Action: Rerun the job, but divide the complicated 
command line into several smaller command lines that do the 
same operations. 


LBR -- WORK FILE I/O ERROR 


Explanation: A write error has occurred on the LBR_- work 
file. One of the following conditions may exist: 


® The volume is full. 

@ The device is write-protected. 

8 The hardware has failed. 

User Action: If the volume is full, delete all unnecessary 
files and rerun LBR. If the device is write-protected, 
write-enable the device and reenter the command line. rt 


the hardware has failed, swap devices and retry the command, 
Or wait until the device is repaired and rerun LBR. 


CHAPTER 9 
RESOURCE MONITORING DISPLAY (RMD) 


The Resource Monitoring Display (RMD) is a privileged .task that 
displays information about the resources in your system. This 
information includes the active tasks, their location in memory, 
the amount of memory they occupy, and available pool space. 


9.1 INTRODUCTION 


RMD consists of pages. A page consists of 24 lines. The program 
contains two kinds of pages: display and setup. 


9.1.1 Display Pages 
There are four display pages available: 
@® Memory (M) 
@e Active Task List (A) 
e Task Header (T) 
e Help (H) 


You press the terminal keys indicated in parentheses to switch 
display pages. 


9.1.2 Setup Pages 
There are three setup pages. Each setup page is associated with 


a display page. (The Help Display Page has no associated setup 
page.) You access a setup page from a display page by pressing 
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the CTRL-[ sequence on your terminal. The setup page documents 


and prompts you for setup commands, which alter the content 
the information displayed on the associated display page. 


9.2 INVOKING RMD 


You can invoke RMD in three ways: 


1. Invoke the SHOW MEMORY command, which in turn invokes 


of 


RMD. 


See Chapter 3 for a description of the SHOW MEMORY command. 


2. Invoke the SHOW TASKS/DYNAMIC command, which in turn invokes 


RMD. See Chapter 3 for a description of the 
TASKS/DYNAMIC command. 


3. Invoke RMD directly from the DCL command level. 


To invoke RMD directly from the DCL command level, enter 
following command: 


SHOW 


the 


$ RUN SRMD 
After entering the command, you see the memory display page on 
your terminal screen, indicating that you are in the RMD 
environment. Once you are in the RMD environment, RMD waits’ for 
your command. 
RMD accepts command lines in the following general format: 
[page][,setupcommand] 
page 
One of the display page abbreviations (M, A, T, or H). The 
default page is the Memory Display (M). 
setupcommand 
A valid setup command for the display page that you have 
selected. The setup commands are the same as_ those 
available to you from the setup page associated with the 


display page you specified. The default setup commands are 


discussed in Sections 9.4through 9.6, which describe 


the 


content of each display page and how you use setup commands 


to alter display parameters. 


INVOKING RMD 


9.2.1 Running RMD on a Second Terminal 


You can connect a second terminal to the Professional through its 
printer port. (For details, see the section on debugging an 
application in the Tool Kit User’s Guide). 


Enter the following commands, either from the keyboard or from an 
indirect command procedure: 


S SET TERMINAL /TT2: /NOSLAVE 
S ASSIGN/TASK RMD TT2: 1 
S ASSIGN/TASK RMD TT2: 2 
S SPAWN SHOW MEMORY 


This command sequence does the following: 


® It reassigns LUNs 1 and 2 to the terminal on which you want 
to run the task, and 


@ It invokes the task on the second terminal while allowing you 


to continue entering DCL commands at the Professional’s 
terminal. 


NOTE 


You must be a privileged user to issue the _ SET 
TERMINAL /TT2: command. 


9.3 THE HELP DISPLAY 


The Help Display documents how you switch display pages. You 
Switch display pages by pressing a terminal key as follows: 


Key Explanation 

M Accesses the Memory Display 

A Accesses the Active Task Display 
si Accesses the Task Header Display 


The Help Display also documents how to exit from RMD and use the 
CTRL-[ sequence to access setup pages from their associated 
display pages. (Because there is nothing to alter on the Help 
Display, no setup page is available from the Help Display.) 


The Memory, Active Task, and Task Header Displays use the entire 
screen. Therefore, you receive no prompts or documentation on 
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display pages. To find out how to access a setup page from a 
display page or how to switch display pages, press the H key (for 
Help) to access the Help Display. 


9.4 THE MEMORY DISPLAY 


The Memory Display graphically represents system memory. ie 
shows the approximate size and locations of partitions and active 
tasks, pool statistics, the name of the currently-executing task, 
and other information regarding operating system status. You 
access the Memory Display from another display page by pressing 
the M key (for Memory). If you invoke RMD without specifying a 
display page, RMD defaults to the Memory Display. 


Figure 9-1 shows the Memory Display. See the numbered notes 


following the figure for a description of each item in the Memory 
Display. 
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Figure 9-1: Memory Display for P/OS 
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Notes to Figure 9-1 


(1) 
(2) 


Operating system type, version number, and base level. 


A one- to six-character name that is a DECnet node name (if 
DECnet iS running on your system). 


Size in K words of the system memory. 


Time elapsed in units of days, hours, and minutes, since the 
system was last booted. 


Current date and time. 


Name of the task that is currently executing or, if none is 
executing, *IDLE* (Executive executing the idle loop). 


Number of free blocks on the first four FILES-11 devices in 
your system. If a device is dismounted, RMD displays: 
"DMO". If a device is off line, RMD displays: "OFL". 


Pool (dynamic storage region) information in the format: 


POOL=X: Y:Z 


» 4 

Number of words in the largest free block in pool 
Y 

Number of free words in pool 
Z 


Number of fragments in the pool free list 
The second line records the worst case of pool since you 
invoked RMD. This line is most useful if RMD has been 
running on a second terminal since the last system boot. 


Secondary pool information in the format: 


SECPOOL=A:B:C% 


Number of free blocks in secondary pool 


Total number of blocks in secondary pool 
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Percentage of secondary pool that is free 


The second line records the worst case of secondary pool 
Since you invoked RMD. This line is most useful if RMD has 
been running on another terminal since the last system boot. 


Partitions in the system using the format: 
partitionname:type 

type 
One of the following: 


D System-controlled (dynamic) partition 
P Secondary pool partition 


Number of tasks in memory and amount of memory they use, and 
number of active tasks swapped or checkpointed out of memory 
and the amount of memory they would require. 


Name of each task, common, or driver in memory and its 
location in memory using the following symbols to designate 
Size, type (task, common, or driver), and other attributes: 


Symbol Attribute 

< > Active task 

[ ] Task not active, yet occupies memory 

: : Named common 

+ + Unnamed common (displayed name is first 


attached task) 
( ) Loaded driver using device mnemonic 
se ee Task not fixed in memory 
=== Task fixed in memory 


The hyphens and equal signs represent the amount of memory 
that each task, driver, or common occupies. Where the 
display shows only one delimiter and no hyphens or equal 
Signs, the open delimiter is in the same location as the 
closing delimiter of the preceding task. 


Partition size and _ location. The beginning of each 
partition is marked with the same symbols as those listed 
previously, plus the following additions: 
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E Executive 
P Pool 


The lines of asterisks are proportional representations of 
the amount of memory occupied by each partition. The 
numbers are in 1K word increments. Each numerical character 
also represents the same amount of memory as an asterisk. 
RMD always divides the system memory into groups of eight 
Uns: 


(14) System error count sequence recorded by the Error Logger 
(always zero if Error Logger not present in your system). 


9.4.1 Altering the Memory Display from the Setup Page 


To alter the Memory Display, you press the CTRL-[ sequence, which 
accesses the setup page for the Memory Display. The setup page 
documents and prompts you for commands which you use to alter the 
Memory Display. You can enter multiple commands after each 
prompt by using commas as_ separators. The setup commands 
available for altering the Memory Display are: 


@ FREEx=ddnn: where x is a number from 0 to 3 and ddnn: is a 
device name and number 


@ RATE=s where s is the replot rate in seconds 


You can truncate these commands to their shortest unique forms. 
These setup parameters stay in effect until you alter them, even 
if you switch to another display page and back to the Memory 
Display. 


9.4.1.1 The FREE Command - You use this command to determine the 
four FILES-11 devices for which you want the Memory Display to 
Show the available free blocks. This information is (7) in 
Figure 9-1. The default is your system disk (SY:) and the next. 
three FILES-11 devices in your configuration. 


9.4.1.2 The RATE Command - You use this command to determine how 
often RMD replots the Memory Display. The default replot rate is 
once per second. 
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9.5 THE ACTIVE TASK DISPLAY 

The Active Task Display shows you the active tasks in the system. 
You access this display from another display page by pressing the 
A key (for Active Task). 

This display has six fields: 

@® Name of the task 

@ Length of the task in octal bytes 

® Terminal that issued the task 

@e Running priority of the task 

@e Outstanding I/O count 


e Status flags 


The status flags use the same mnemonics as the SHOW TASK/FULL 
command. See Chapter 3 for definitions of the status flags. 


9.5.1 Altering the Active Task Display from the Setup Page 


To alter the Active Task Display, you press the CTRL-[ sequence, 
which displays the setup page for the Active Task Display. The 
setup page documents and prompts you for commands that you use to 
alter the Active Task Display. You can enter multiple commands 
after each prompt by using commas as separators. The setup 
commands available for altering the Active Task Display are: 


@e OWNER=ttnn: where ttnn: is the terminal that issued the 
task 


@® PRIORITY=p where p is a task’s running priority 
@ RATE=s where s is the replot rate in seconds 
e TASK=taskname where taskname is the name of the task whose 


header you want to display 


You can truncate these commands to their shortest unique forms. 
These setup parameters stay in effect until you alter them, even 
if you switch to another display page and back to the Active Task 
Display. 
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9.5.1.1 The OWNER Command - This command allows RMD to display 

only those tasks that have been issued by a particular terminal. 
The default is ALL, which displays tasks issued from all 
terminals. 


9.5.1.2 The PRIORITY Command - The active task list may be too 
long to fit on one screen. You use the PRIORITY command to 
determine the highest priority tasks that you want to. See. The 
default is 250, the highest possible priority. 


9.5.1.3 The RATE Command - This command allows you to determine 
how often RMD replots the Active Task Display. The default 
replot rate is once per second. 


9.5.1.4 The TASK Command - This command allows you to look at a 
specific task header. This command is an exception because it 1s 
the only setup command that switches display pages. There 1s _ no 
default for the TASK command. The Task Header Display is 
discussed in Section 9.6. 


9.6 THE TASK HEADER DISPLAY 

The Task Header Display shows you the task header of the task you 
Specify. You access this display from another display page by 
pressing the T key (for Task Header). If no task is currently 
specified, RMD shows you the setup page first so that you can 
specify the task whose task header you want RMD to display. 


The Task Header Display shows you the following information about 
the specified task: 


@® Name of the task 
@® Name of the partition in which the task runs 


e Status flags, which have the same mnemonics as in the Active 
Task display 


@ Owner of the task by terminal number 


@® Outstanding I/O count 
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e Default priority 

e Running priority 

@ Swapping priority 

@e Length in decimal words 


e Contents of the six general purpose registers, the program 
counter, and the Processor Status Word 


e Contents of the Directive Status Word (SDSW) 
@ Local event flags 


e Logical unit number (LUN) assignments to a maximum of 26 LUNs 


When RMD displays file names in the list of LUN assignments, the 
filename and directory displayed are the filename and directory 
of the file when it was created. If the file has been renamed, 
the RMD display may not reflect the current directory and/or 
filename. 


9.6.1 Altering the Task Header Display from the Setup Page 


‘To alter the Task Header Display, you press the CTRL-[ sequence, 
which displays the setup page for the Task Header Display. The 
setup page documents and prompts you for commands that alter the 
Task Header Display. You can enter multiple commands after each 
prompt by using commas as_ separators. The setup commands 
available for altering the Task Header Display are: 


@e RATE=s where s is the replot rate in seconds 


e TASK=taskname where taskname is the name of the task whose 
header you want to display 


You can truncate these commands to their shortest unique forms. 
These setup parameters remain in effect until you alter then, 
even if you switch to another display page and back to the Task 
Header Display. 


9.6.1.1 The RATE Command - This command allows you to determine 
how often RMD replots the Task Header Display. The default 
replot rate is once per second. 
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9.6.1.2 The TASK Command - This command changes the task header 
to be displayed. There is no default. The TASK command has the 
same function as the TASK command on the Active Task Display, 
except that here it does not switch display pages. 


9.7 ERROR MESSAGES 


RMD generates the following error messages: 


RMD - Allocated screen buffer too small for this device 
Explanation: RMD requires more internal memory to display 
the requested display on the type of terminal on which you 
are running RMD. 


User Action: Call your DIGITAL Customer Support Center. 


RMD - Illegal command - xxxxx 
Explanation: You entered an illegal command xxxxx either on 
the command line or in response to the COMMAND> prompt ona 
setup page. 
User Actions Enter the correct command as documented in 
this chapter. 


RMD - Page does not exist 


Explanations You requested a display page from the command 
line that does not exist. 


User Actions Enter the command line again specifying a 
correct display mnemonic. 

RMD - Segment ’xxxxxx’ not found 
Explanation: The module xxxxxx was not found in the task 
image for RMD. This denotes an error in how RMD was 


task-built. 


User Actions: Call your DIGITAL Customer Support Center. 
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RMD - Terminal type not defined 


Explanations: The operating system and RMD do not’ recognize 
your terminal type. 


User Actions Check your terminal type using the command 


SHOW TERMINAL. If this setting is incorrect, use the SET 
TERMINAL command to correct your terminal type setting. 


RMD - Terminal type not set 
Explanation: You did not build RMD to display the requested 
display page on the type of terminal to which your terminal 


1s set. 


User Actions: Determine your terminal type setting uSing the 


command SHOW TERMINAL. If this setting 1S incorrect, use 
the command SET TERMINAL to correct your terminal type 
setting. 


RMD - Terminal type not yet supported 
Explanations RMD does not recognize your terminal type. 


User Actions Determine your terminal type setting using the 


command SHOW TERMINAL. If this setting is incorrect, use 
the command SET TERMINAL to correct your terminal type 
setting. 


CHAPTER 10 
TASK/FILE PATCH PROGRAM (ZAP) 


The Task/File Patch Program (ZAP) allows you to directly examine 
and modify task image and data files on a FILES-11 volume. Using 
ZAP, you can patch these files interactively without reassembling 


and rebuilding the task. 
ZAP supports four types of task image files: 


e Regular task image files, which include those mapped _ to 
resident and supervisor mode libraries 


e Multiuser task image files 
e tI- and D-space (instruction and data space) tasks 


e Resident libraries 


NOTE 


I- and D-space and supervisor mode libraries are 
not currently supported. 


These types of task image files are discussed fully with the 
/List switch (refer to Section 10.1.1). 


ZAP performs many of the functions performed by the RSxX-11 
on-line debugging utility, ODT. Thus, working knowledge of ODT 
is helpful in using ZAP. See the IAS/RSX-11 ODT Reference Manual 
for more information on ODT. 


ZAP provides the following features: 
@e Operating modes that allow you to access specific words’ and 
bytes in a file, modify locations ina file, list the disk 


block and address boundaries for each overlay segment in a 
task image file on disk, and open a file for reading only. 
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e A set of internal registers that include eight Relocation 
Registers. 


@ Single-character commands that, with other command line 
elements, allow you to open and close locations ina file and 
to display and manipulate the values in those locations. 


Although the ZAP program is relatively straightforward to use, 
patching locations ina task image file requires knowing how to 
use the map (or memory allocation file) generated by the Task 
Builder and the listings generated by the MACRO-11 
assembler. These maps and listings provide information you need 
to access the locations whose contents you want to change. For 
information on Task Builder maps, see the RSX-11M/M-PLUS' and 
Micro/RSX Task Builder Manual. For information on MACRO-11 
listings, see the PDP-11 MACRO-11 Language Reference Manual. 


10.1 ZAP OPERATING MODES AND SWITCHES 


ZAP provides two addressing modes and two access modes. The 
addressing modes are task image mode and absolute mode. Task 
image mode is the default mode. The access modes are read/write 
mode and read-only mode. Read/write is the default mode. Either 
addressing mode can be used with either access mode. The modes 
and their associated switches are as follows: 


@e Task image mode is the default addressing mode for ZAP. In 
this mode, addresses in ZAP command lines refer to addresses 
in the task image file as they are shown in the Task Builder 
map for the file. Refer to Section 10.1.1.2 for more 
information on using task image mode. 


@ In absolute mode, specified with the /AB_ switch, ZAP 
processes the addresses you enter in ZAP command lines as 
absolute byte addresses within the file. You must use 
absolute mode for any files that are not task images. Refer 
to Section 10.2.2 for more information on using absolute 


mode. 


@e Read/write mode is the default access mode for ZAP. In this 
mode, ZAP opens a file for reading and/or modification. 


e In read-only mode, specified with the /RO switch, ZAP opens a 
file for reading but not modification. That 1s, you can 
execute ZAP functions that change the contents of locations, 
but these changes are not actually made to the file. When 
ZAP exits, the original values in the file are still there. 
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10.1.1. The List Switch (/LI) 


When using ZAP in task image mode (but not absolute), you can 
also specify the /List switch (/LI). The /List switch displays 
the overlay segment table for the on-disk task image file with 
which you are working. The table lists the starting disk block 
and address boundaries for each overlay segment in the file. The 
segment table lists are ina different format for each type of 
task image file. The table and Task Builder map allow you to 
locate the task segments being changed. 


The /LI switch displays the overlay segment boundaries in the 
following format: 


ssssss: aaaaaa-bbbbbb [nnnnnn] [dddddd] 
SSSSSS3 
The starting block in octal. 
aaaaaa 
The lower address boundary in octal. 
bbbbbb 
The upper address boundary in octal. 
nnnnnn 
The segment name that appears for I- and D-space tasks; 
manually loaded overlays (SLOAD); memory-resident overlays; 
tasks that link to the library with memory-resident 
overlays; or for any combination of the previous conditions. 


dddddd 


The description of the segment type string which appears 
next to the segment name in the segment table. 


The following sections describe the /List switch formats for the 
different kinds of task image files. Section 10.6.6 gives 
examples of the segment table lists. 


10.1.1.1 The /LI Switch and Regular Task Image Files - For 
regular task image files, including those mapped to resident and 
supervisor mode libraries, the /LI switch displays the task’s 
overlay segments in the order of their location in the file. 
Each segment begins on an even block boundary. 
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10.1.1.2 The /LI Switch and Multiuser Task Image Files 


For multiuser tasks, the /LI switch lists the starting disk block 
number and address boundaries of each segment. In addition, the 
address boundaries of the shared read-only segment are listed. 
The block number that is used to reference the multiuser segment 
1s the same as the root segment. The multiuser segment is an 
extension of the root segment. The segment list disk block 
numbers have a corresponding entry in the Task Builder map. 


See the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for more 
information on multiuser tasks. 


10.1.1.3 The /LI Switch and Resident Libraries - For 
resident libraries, the /LI switch displays each of the task’s 
segments as beginning on a new block boundary. However, the 
segments may not actually begin on even boundaries because of 
compression by the Task Builder. Resident libraries can be 
overlaid, but each overlay segment must also be resident in 
memory. 


To avoid the possibility that two or more segments in a single 
block could have the same virtual address, ZAP treats the 
resident library in the same way that the Task Builder does. The 
Task Builder builds the library with each segment beginning on an 
even block boundary, but then compresses the segments in the task 
file itself. The Task Builder map is generated before the 
segments are compressed, so the boundaries given in the map do 
not necessarily correspond to the actual location of the 
segments. 


The disk block boundaries given in the Task Builder map file are 
the ones that ZAP uses to address locations in the resident 
library and that the /LI switch displays in its segment table. 


They do not use the actual starting blocks of the segments. (You 
should be aware of this when you are working with resident 
libraries in absolute mode. However, also remember that you 


cannot use the /LI switch in absolute mode.) 


You should also note that ZAP cannot know the physical starting 
addresses for the segments of an overlaid resident library 
because its overlay structure is stored in the symbol definition 
(.STB) file, not with the task image file itself. For ZAP, each 
segment’s starting address is 000000. 


See the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for more 
information on resident libraries. 
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10.1.1.4 The /LI Switch and I- and D-Space Tasks - For’ I- and 
D-space tasks, the /LI switch lists the starting block number and 
the address boundaries of each segment. The I-space or D-space 
segment may be suppressed in the listing when, for example, a 
segment with only I-space code does not include a listing for a 
D-space segment. If the segments are not suppressed, the segment 
list disk block numbers have a corresponding entry in the Task 
Builder map. 


10.2 ADDRESSING LOCATIONS IN FILES 


To address locations in a file, ZAP provides two addressing modes 
(task image and absolute, described above) and a set of internal 
registers, which includes eight Relocation Registers. This 
section first introduces the concept of relocation biases and the 
use of the Relocation Registers, then explains how to use the 
addressing modes. 


10.2.1 Relocation Biases 


When MACRO-11 generates a relocatable object module, the base 
address of each program section of the module is 000000. In the 
assembler listing, all locations in the program section are shown 
relative to this base address. 


The Task Builder links program sections to other program sections 
by mapping the relative addresses applied by the assembler to the 
physical addresses in memory (for unmapped systems) or to virtual 
addresses (for mapped systems). 


Many values within the resulting task image are biased by a 
constant whose value is the absolute base address of the program 
section after the section has been relocated. This bias is 
called the relocation bias for the program section. 


ZAP’s eight Relocation Registers, OR through 7R, are generally 
set to the relocation biases of the program sections to be 
examined. This allows you to refer to a location in a module by 
the same relative address that appears in the MACRO-11 listing. 
The addressing modes help you calculate the relocation biases. 


10.2.2 ZAP Addressing Modes 


As explained in Section 10.1, ZAP’s two modes for addressing 
locations ina file are task image mode and absolute mode. Task 
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image mode is the default mode for ZAP. 
explain how to use these modes. 


The following examples show excerpts from a MACRO-11 
the module MYFILE and a Task Builder map. 
accompanying text show how to use ZAP in task 


following lines represent assembled instructions from a MACRO-11 


source listing: 


The 


next two sections 


listing of 
These excerpts and the 
image mode. The 


71 000574 032767 0Q000000G 000000G BIT #FE.MUP,SFMASK 

72 000602 001002 BNE 2S 

73 000604 000167 000406 JMP 305 

74 000610 016700 000000G 23: MOV STKTCB,RO 

75 000614 016000 000000G MOV T.UCB(RO),RO 

76 000620 010067 177534 MOV RO,UCB 

77 000624 032760 #U2.HLD,U.CW2(RO0) 


000000G 000000G BIT 


The following lines from a Task Builder map give the information 
you need to address locations in the task image file as they 
appear in the above MACRO-11 listing: 


120000 123023: 003024 01556. 
000002 000005 000004 00004. 


LIMITS: 
LIMITS: 


R/W MEM 
DISK BLK 


MEMORY ALLOCATION SYNOPSIS: 


SECTION TITLE IDENT FILE 
BLK. RW; 1 (LCL; REG, CON): 120232 002546 01382. 
120232 002244 01188. MYFILE O1 MCR.OL 
122476 000064 00052. FMTDV Oi MCR.OL 
SSRESL:(RW,1I,LCL,REL,CON) 123000 000024 00020. 
the 


Using information in the Task Builder map, you can determine 
block number and byte offset for the beginning of the file you 
want to change. The disk-block-limits line lists block 2 as’ the 
block where the program code begins. The synopsis lists byte 
offset 120232 as the beginning of the file MYFILE. To address 
location 574 in the MACRO-11 listing in task image mode, specify 
the following command line: 


2:120232+574/<RET> 
ZAP responds by opening the location and displaying its contents: 


00221210267 032767 
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10.2.2.1 Using the Task Image Addressing Mode - In task image 
mode, ZAP allows you to address locations ina task image file by 
uSing the addresses the MACRO-11 assembler displays in its 
listing and the starting block number and byte offset listed in 
the Task Builder map. Unlike absolute mode, task image mode is 
useful for working with locations in an overlaid file because the 
Task Builder and ZAP perform the calculations necessary to relate 
the file’s disk structure to its run-time memory structure. 


10.2.2.2 Using the Absolute Addressing Mode - In absolute mode, 
ZAP processes the addresses you enter in the command lines as 
absolute byte addresses within the file. To use ZAP in absolute 
mode, invoke ZAP and enter the /AB switch with the file 
specification. 


ZAP interprets the first address in the file you are changing as 
virtual block 1, location 000000. All other addresses you enter 
are interpreted using this address as the base location. 
Absolute mode allows you to access all the bytes ina data or 
task image file as well as the label and header blocks of a_ task 
image file on disk. However, to modify a disk task image, you 
must know the disk layout of the task image. Generally, absolute 
mode is practical only for data files or for task image files 
that are not overlaid. 


10.3 INVOKING AND TERMINATING ZAP 
To invoke ZAP type: 

S RUN S$ZAP 
ZAP will prompt you: 

ZAP> 
You cannot enter a file specification on the same line that you 
use to invoke ZAP unless the file is an indirect command file. 
Refer to Section 10.3.1. When ZAP prompts you, enter the file 
specification for the file you want to change. You enter the 
file specification in the format: 


dev: (directory]filename.filetype;version[/sw... ] 


The default file type is .TSK. After you enter the file 
specification, ZAP prompts with an underscore (_). 
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You terminate ZAP by entering the X command (explained in Section 
O06 41): This command exits you from ZAP and returns control to 
your DCL. 


10.3.1 Using Indirect Command Files with ZAP 


An indirect command file contains the specification for the file 
you want to work with and the appropriate ZAP commands. You can 
specify the indirect command file in the same command line in 
which you invoke ZAP. 


The following sample indirect command file (called CHANGE.CMD) 
contains ZAP commands. The commands will change the default 
priority of the despooler from 70 to 80 (120 octal). The V 
command is used to verify that 70 (106 octal) is what is actually 
in the location to be changed. The command file has the 
following ZAP commands: 


LPP.TSK/AB 
G2 3467 
106V 

120 

4 


To use the indirect command file type the following: 
ZAP> @CHANGE 


In this command, ZAP executes the commands in the file named 
CHANGE.CMD. 


The commands being used first open the task image file (LPP.TSK) 
in absolute mode (/AB). The next two commands open the desired 
location (byte 346 in block 0) and verify its contents (106). 
The next command changes the contents to 120, which will be the 
new default priority for the despooler. The X command exits you 
from ZAP and returns control to DCL. 


10.4 THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS 
ZAP commands perform functions that allow you to examine and 


modify the contents of locations in a file. Command lines 
comprise combinations of the following elements: 
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® Commands 

e Internal registers 

@® Arithmetic operators 

® Command line element separators 

@e The current location symbol 

@® Location-specifier formats 
The command elements can be combined to perform multiple 
functions. The function of a given command line depends not only 
on which elements you use, but also on the position of one 


element in relation to the next. 


The following sections describe the ZAP command line elements. 


10.4.1 ZAP Commands 

There are three types of ZAP commands: 
® Open/close location commands 

e General purpose commands 

@® <RETURN>D key 


The following sections describe each type of command. 


10.4.1.1 Open/Close Location Commands - Open/close location 
commands are nonalphanumeric ASCII characters that direct ZAP to 
perform a sequence of functions. Open/close commands specify two 


general sequences of operations: 


@ Open a location, display its contents, and store the contents 
in the Quantity Register (see Section 10.6.2). 


e Close the location after (optionally) modifying it and open 
another location as specified by the command. 


Section 10.6 describes the format for specifying open/close 
location commands. 
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10.4.1.2 General Purpose Commands - ZAP provides Six 
Single-character, general purpose commands. You use these 
commands for calculating displacements, verifying location 
contents, and exiting from ZAP. You can enter some of the 
commands on the command line with no other parameters. 


10.4.1.3 <RETURN> Key - Unless there is another value or command 
on the line, the <RETURN> key closes the current location as 
modified and opens the next sequential location. ZAP commands 
take effect only after you press the <RETURN> key. 


10.4.2 ZAP Internal Registers 


ZAP internal registers are fixed storage locations that ZAP uses 
as registers. These registers contain values set by both you and 
ZAP. ZAP provides the following internal registers: 


@e Relocation Registers 0 through 7 (OR through /7R). These 
registers provide a means for indexing into a program section 
to change the contents of locations in the program _ section. 
You load the registers with the base address of the program 
section that has been relocated by the Task Builder. 


@e The Constant Register (C). You set this register to contain 
a 16-bit value, which you can specify as an expression in the 
ZAP command line. 


e The Format Register (F). This register controls the format 
of the displayed address. If the value of the F Register is 
0 (the initial value), ZAP displays addresses relative to the 
largest value of any Relocation Register whose value is less 
than or equal to the address to be displayed. If the value 
of the Format Register is not 0, ZAP displays addresses in 
absolute byte format. 


e The Quantity Register (Q). ZAP sets the value in the 
register to be the last value displayed at your terminal. 


To access the contents of a register, specify a dollar sign (S$) 
preceding the register name (in this case, C) in the command 
line. For example: 


_S$C/<RET> 
Sc/7 000000 


This command line directs ZAP to display the contents of the 
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Constant Register. The slash (/) is an open command described in 
Table 10-3. 


10.4.3 ZAP Arithmetic Operators 


Operators are single-character command line elements that define 
an arithmetic operation. Generally, ZAP evaluates these 
expressions as addresses. Table 10-1 describes the operators. 


You use the operators in expressions in command lines. For 
example, rather than manually adding all the displacements listed 
in the Task Builder map, you can specify a location using the 
following notation: 


_2:120000+170/<RET> 
This method for calculating such a displacement is faster and 


more accurate than doing it manually. 


Table 10-1: ZAP Arithmetic Operators 


Operator Function 


+ The plus sign adds a value to another value. Use 
it in an expression that ZAP then evaluates to be 
a command line element. 


- The minus sign subtracts a value from another 
value. Use it an expression that ZAP then 
evaluates to be a command line element. 


* The asterisk multiplies a value by 50 (octal) and 


adds it to another value. Use it to forma 
Radix-50 string. 


The following example shows how to use the asterisk (*) to form 
Radix-50 strings. 
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_0,40/<RET> 
002:0,000040/ 000001 
_1*33<RET> 

_/<RET> 

002:0,000040/ 000103 
_%<RET> 

002:0,000040% AS 


In this example, the first command opens the locations that is 40 
bytes offset from the location address contained in Relocation 
Register 0 and displays in octal format the contents of the new 
Location. The location contains the value 000001. The second 
command converts 000001 to Radix-50 and adds 33 to the Radix-50 
value. The slash (/) command again displays in octal the value 
contained in the offset location. The value is now 103. The 
percent sign (%) command displays 103 in Radix-50 format. 


10.4.4 ZAP Command Line Element Separators 


ZAP provides separators to delimit one command line element from 
another. Different separators are required depending on the type 
of ZAP command being executed. See Table 10-2. 


Table 10-2: ZAP Command Line Element Separators 


Separator Function 


? The comma separates a Relocation Register 
Specification from another command line element. 


; The semicolon separates an address from an 
internal register specification. Used in 
expressions that set values for Relocation 


Registers. 
The colon separates a block number base value from 


a byte offset into the block. Used in most of the 
references to locations ina file. 


10.4.5 ZAP Command Line Location-Specifier Formats 


ZAP has four formats for specifying locations in a command line. 
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Each provides a means of indexing into a file. 
The formats are: 

e Current location symbol 

@e Byte offset 

@ Block number:byte offset 


@e Relocation register, byte offset 


10.4.5.1 The Current Location Symbol - In command line 
expressions that ZAP evaluates as addresses, a period (.) 
represents the last open location. 


10.4.5.2 Byte Offset Format - You specify the byte offset format 
as follows: 


location 
If you are using ZAP in absolute mode, ZAP interprets this 
Specification as a byte offset from block 1, location 000000. 
This format is generally useful only when you are using absolute 


mode. 


The following ZAP command line opens absolute location 664 and 
displays its contents in octal format: 


_664/<RET> 


10.4.5.3 Block Number: Byte Offset Format - This format allows 
you to specify a byte offset from a specific block in the file. 
Specify the format as follows: 


blocknum:byteoffset 


You can use this format for addressing locations whether or not 
you enter the /AB switch with the file specification. 


In task image mode, ZAP allows you to enter the block number’ and 


byte offset displayed in the Task Builder map. The map gives 
information on the overlay segments in a task image file. 
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10.4.5.4 Relocation Register, Byte Offset Format - This format 
allows you to load a Relocation Register with the address of a 
location. The address is then used as a_ relocation bias. You 
specify this format for addressing locations in a task image file 
as follows: 


relocreg,byteoffset 


Specify relocreg in the form nR, where n is the number of the 
Relocation Register. You can then address byte offsets from the 
address loaded in the Relocation Register. For example: 


_2:001254; 3R<RET> 
_3,64/<RET> 
002:3,000064/ 037334 


The first command loads the address 001254 into Relocation 
Register 3, then the second command opens the location that is 64 
bytes offset from block 2, location 001254. The contents of that 
location are 037334. 


10.5 USING ZAP OPEN AND CLOSE COMMANDS 


This section gives examples of how to use the ZAP open and close 
commands. These commands allow you to open locations ina file, 
modify those locations, and close the locations. 


Table 10-3 summarizes the open and close commands 


Table 10-3: ZAP Open and Close Commands 


Command Name Description 


/ Slash Opens a location, displays its 
contents in octal, and stores 
the contents of the location in 
the Quantity Register (Q). If 
the location is odd, it is 
opened as a byte. 


‘ Quotation mark Opens a location, displays the 
contents of the location as two 
ASCII characters, and stores the 
contents of the location in the 
Quantity Register (Q). 
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Name 


Percent sign 


Backslash 


Apostrophe 


RETURN key 


Circumflex or 
Up-arrow 


Underscore or 
Back-arrow 


At sign 


Description 


Opens a location, displays the 
contents of the location in 
Radix-50 format, and stores the 
contents of the location in the 
Quantity Register (Q). 


Opens a location as ae byte, 
displays the contents of the 
location in octal, and stores 
the contents of the location in 
the Quantity Register (Q). 


Opens a location, displays the 
contents as one ASCII character, 
and stores the contents of the 
location in the Quantity 
Register (Q). 


Closes the current location as 
modified and opens the next 
sequential location if no other 
values or commands are on the 
command line. ZAP commands take 
effect only after you press’ the 
RETURN key. 


Closes the currently open 
location as modified and opens 
the preceding location. 


Closes the currently open 
location as modified, uses the 
contents of the location as an 


offset from the current 
location, and opens the new 
location. 

Closes the currently open 


location as modified, uses the 
contents of the location as an 
absolute address, and opens that 
location. 


LOSS 


USING ZAP OPEN AND CLOSE COMMANDS 


Command Name Description 
> Right angle Closes the currently open 
bracket location as modified, interprets 


the low-order byte of the 
contents of the location as’ the 


relative branch offset, and 
opens the target location of the 
branch. 
< Left angle Closes the currently open 
bracket location as modified, returns to 
the location from which the last 
series of underscore (__), at 


Sign (@), and/or right angle 
bracket (>) commands began, and 
opens the next sequential 
location. 


10.5.1 Opening Locations in a File 


Use any of the ZAP open commands -- slash (/), quotation mark 
("), percent sign (%), backslash (\), or apostrophe (’) -- to 
open a location ina file. The format ZAP uses to display the 
contents of the open location depends on which operator you use. 


Once you open a location in a given format, ZAP displays in that 
format any other locations you open. For example, if you enter 
the percent sign (%) command, the contents of the open location 
are displayed in Radix-50 format. If you continually press the 
<RETURN> key, consecutive locations are displayed in Radix-50 
format until you change the format by entering a different 
special-character open command. 


10.5.2 Changing the Contents of a Location 


When you open a location with a special-character open command, 
you can change the contents of that location by entering the new 
value and pressing the <RETURN> key. The following example 15 a 
sequence of commands and ZAP responses that show how to open a 
location, change the value of the location, and close _ the 
Location. 
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_/<RET> 
002:120000/ 000000 
_44444<RET> 
_/<RET> 
002:120000/ 44444 


The first command (/) displays in octal format the contents 
(000000) of the current location. The contents are changed by 
entering the value 44444 and then the location is closed as 
modified by pressing the <RETURN> key. The slash (/) and 
<RETURN> key display the new contents of the location (last line 
of example). 


10.5.3 Closing Locations in a File 


ZAP uses the <RETURN> key and other special-character commands 
for closing a location ina file. The close commands perform 
three functions: 


e Close the current location 


@® Direct ZAP to another location (such as the preceding 
location or a location referred to by the current location) 


@e Open the new location 


The following sections give examples of how each command works. 


10.5.3.1 Closing a Location and Opening the Preceding 

Location - Use the circumflex (*) or up-arrow (#) 
command (depending on the type of terminal you are using) to 
close the current location, to direct ZAP to the preceding 
location, and to open that location. The following sequence of 
ZAP commands and responses shows how this command works: 


_2:120100/<RET> 
002:120100/ 000000 
_<RET> 

002:120102/ 000111 
_<RET> 

002:120104/ 000222 
_<RET> 

002:120106/ 000333 
_* <RET> 
002:120104/ 000222 
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The <RETURN> key closes the first three open locations and_ then 
opens the next location. The circumflex command closes location 
120106 and directs ZAP to open the preceding location, 120104. 


10.5.3.2 Closing a Location and Opening an Offset Location - 
Use the underscore (_) or back-arrow (#) command to close the 
current location, to direct ZAP to use the contents of the 
current location as an offset from the current location, and to 
open the new location. The following sequence of ZAP commands 
and responses shows how this command works: 


_2:120100/<RET> 
002:120100/ 000000 
_<RET> 

002:120102/ 111111 
_<RET> 

OO2Z21 201047 222222 
_<RET> 

002:120106/ 000022 
__<RET> 
002:120132/ 123456 


The <RETURN> key closes the first three open locations. The 
underscore command closes location 120106, directs ZAP to use the 
contents (22) of the current location as the offset from _ the 
current location (120110), and then opens that offset location 
(1. 207932')s 


10.5.3.3 Closing a Location and Opening an Absolute Location - 
Use the at sign (@) command to close the current location, to 
direct ZAP to use the contents of the just-closed location as the 
absolute address of a location, and to open that location. 


The following sequence of ZAP commands and responses shows’ how 
this command works: 


_2:120100/<RET> 
002:120100/7 000000 
_<RET> 

00221201027 Tidat1 
_<RET> 

002:1201047 120114 
_@<RET> 
002:120114/ 114114 


The <RETURN> key closes the first three open locations. The at 
Sign command closes 120104, directs ZAP to use the contents 
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(120114) of that location as the absolute address of the next 
location to open, and then opens that location. 


10.5.3.4 Closing a Location and Opening a Branch Target 

Location - Use the right angle bracket (>) command to 
close the current location, to direct ZAP to use the low-order 
byte of the contents of the just-closed location as a branch 
offset for the address of the next location, and then to open 
that location. The following sequence of ZAP commands and 
responses shows how this command works: 


_2:120100/<RET> 
002:120100/7 005000 
_<RET> 

00222201027 005301 
_<RET> 

002:120104/ 001020 
_><RET> 
002:120146/ 052712 


The <RETURN> key closes the first three open locations. The 
right angle bracket command closes location 120104, directs ZAP 
to use the low-order byte (020) of its contents as the branch 
offset for the address of the next location (120146), and then 
opens that location. 


10.5.3.5 Closing a Location and Opening a Previous Location - 
Use the left angle bracket (<) command to close the current 
location; to direct ZAP to the location where the current’ series 
of underscore (_), at Sign (@), and/or right angle bracket (>) 
"HEADER’began; and then to open that location. The following 
sequence of ZAP commands and responses shows how this command 
works: 


_1202;0R<RET> 

051 07<RET> 
002:0,000010/ 005212 
___<RET> 
002:0,005224/ 001020 
_><RET> 
002:0,005266/ 000000 
_@<RET> 
002:0,000000/ 000000 
_<<RET> 
002:0,000012/ 000430 


The underscore command directs ZAP to location 005224. The right 
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angle bracket command directs ZAP to location 005266, and the at 
Sign command directs ZAP to location 000000. The left angle 
bracket command then directs ZAP to location 000012, which is the 
next sequential address after the location where the sequence of 
commands began. 


10.6 USING ZAP GENERAL PURPOSE COMMANDS 
This section explains the functions of ZAP general purpose 


commands and shows the formats for specifying them. Table 10-4 
describes the commands. 


Table 10-4: ZAP General Purpose Commands 


Command Function 
X Exits from ZAP; returns control to DCL. 
K Calculates the offset in bytes between an address 


and the value contained in a Relocation Register, 
displays the offset value, and stores it in the 
Quantity Register (Q). 


O Displays the jump and branch displacements from 
the current location to a target location. 


= Displays in octal the value of the expression to 
the left of the equal sign. | 


V Verifies the contents of the current location. 


R Sets the value of a Relocation Register. 


10.6.1 The X Command 


Use the X command to exit from ZAP and then return control to 
DCI 


Specify the X command in the format: 


X 
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10.6.2 The K Command 


Use the K command to calculate the offset in bytes between an 
address and the value contained ina Relocation Register, to 


display the offset value, and to store it in the Quantity 
Register (Q). 


You can enter the K command in the following formats: 


K Calculates the offset in bytes between the address of 
the currently open location and the value of the 
Relocation Register whose contents are equal to or 
closest to (but less than) the value of that address. 


nK Calculates the offset in bytes between the currently 
open location and Relocation Register n. 


a;nK Calculates the offset in bytes between address a and 
Relocation Register n. 


ZAP responds to the K command by displaying the Relocation 


Register it used and the offset value it calculated in the 
format: 


=reg,offset 
The following example shows how to use the K command: 


_2:1172;0R<RET> 
_2:1232;1R<RET> 
_2:1202/<RET> 
002:000020/ 000111 
_K<RET> 

=Q ,000010 
_0,100;1K<RET>D 
=1,000040 


The first command sets the value of Relocation Register 0 to 
001172. The second command sets the value of Relocation Register 
1 to 001232. The slash command displays in octal format’ the 
contents of location 001202 (000111). The K command calculates 
the physical distance (offset) between the address of the 
currently open location (001202) and the value of the Relocation 
Register whose contents are equal to or closest to (but less 
than) the value of the address. ZAP then displays the number of 
the Relocation Register it used (0) and the offset 
(00010=001202-001172). 


The last command adds 100 to the address in Relocation Register 0 


(001172) and then calculates the offset between the new address 0 
(001272) and the contents of Relocation Register 1 (001232). ZAP 
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then displays the number of the specified Relocation Register (1) 
and the offset (000040=001272-001232). 


10.6.3 The O Command 


Use the O command to display the jump and branch displacements 
from the current location to a target location. A jump 
displacement is the offset between the open location and the 
target location. The jump displacement is used in the second 
word of a jump instruction if the instruction uses’ relative 
addressing. A branch displacement is the low-order byte of a 
branch instruction which, when executed, branches to the target 
location. 


You can enter the O command in the following formats: 


ad Displays the jump and branch displacements from the 
current location to the target of the branch (a). 


a;rO Displays the jump and _ branch displacements from 
location a to target location r. 


The following example shows how to use the O command: 


_0,4534/<RET> 
0,4534/ 1234 

_45660<RET> 
000030> 000014 


_4534;45660<RET> 
_000030> 000014 


The first number (000030) is the jump displacement; the second 
number (000014) is the branch displacement. 


10.6.4 The Equal Sign (=) Command 


Use the equal sign command (=) to display (in octal) the value of 
the expression to the left of the equal sign. 


Specify the equal sign command in the format: 
expression= 


The following example shows how to use the equal sign command 
(note that 177777 equals -1): 


_2:30/<RET> 
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002:000030/ 000000 
_.+177756=<RET> 
000006 


The first command displays in octal format the contents of 
location 000030, which are 000000. The next command adds 177756 
to the address of the currently open location (000030). ZAP then 
displays the value of the specified expression (6=30+177756 or 
6=30-22). 


10.6.5 The V Command 


Use the V command to verify that a location contains a _ specified 
value. 


Specify the V command in the format: 
contentsvV 


You use the V command to ensure that, before you have ZAP change 
them, the contents being changed are what they should be. The V 
command is mainly useful in indirect command files because ZAP 
issues an error message and exits if the contents do not match. 
That way, the contents are not changed incorrectly. 


The following example shows how to use the V command; if you were 


using an indirect command file, you would include this sequence 
of ZAP commands in it. 


ZAP opens the location that is 1200 offset from the value of 
Relocation Register 0 and ensures that the value contained at the 
location is 6. If so, ZAP changes the 6 to 10. If the value is 
not 6, ZAP exits. 


10.6.6 The R Command 

Use the R command to specify the value for a Relocation Register. 
ZAP uses these registers to index into a program section so that 
you can change the contents of locations in the program section. 


Specify the R command in the format: 


_contents;nR 
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The variable n is the number of the Relocation Register (0 
through 7). 


For example: 


_$3R/<RET> 
S3R/ 177777 
_125670;3R<RET> 
_$3R/<RET> 
S3R/ 125670 


The first command accesses the contents of Relocation Register 3, 
which ZAP displays in octal format as specified by the slash. 
The contents of the register are 177777. The next command 
changes the contents of the register to 125670. The last command 
again displays the contents of the register, which have. been 
changed correctly. 


10.7 EXAMPLES 


This section gives examples of ZAP usage. The examples show’ the 
/LI switch segment table format and how you would use some of the 
ZAP commands. 


Some of the ZAP examples in this section are based on information 
contained in the following excerpts from a sample Task Builder 
memory allocation map and from the program code for some of the 
modules in the task. Each example follows the section of program 
code associated with it. 


Excerpts from Task Builder map: 


MAINMEO.TSK;1 Memory allocation map TKB M40.10 Page 1 
14-MAR-83 16201 


Task name te MO 

Partition name : GEN 

Identification : MOO 

Task UIC >: [200,200] 

Stack limits: -000300 G0iL277-001000 00512. 

PRG xfr address: 020520 

Task attributes: ID 

Total address windows: 2. 

Task image size : 9184. words, I-Space 
3520. words, D-Space 

Task Address limits: 000000 043647 I-Space 
000000 015507 D-Space 

R-W disk blk limits: 000002 000102 000101 00065. 
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MAINMEO.TSK;1 Overlay description: 
Base Top Length 
000000 023135 023136 09822. I MAINO 
000000 014123 014124 06228. D 
022140 043645 021506 09030. I INPUT 
014124 015507 001364 00756. D 
022140 022307 000150 00104. I CALC 
014124 014167 000044 00036. D 
~§©022310 «022437 «000130 00088. I AADD 

014170 014173 000004 00004. D 
022310 022437 000130 00088. I SUBB 
014170 014173 000004 00004. D | 
022310 022437 000130 00088. I MULL 
014170 014173 000004 00004. D 
022310 022441 000132 00090. I DIVV 
014170 014173 000004 00004. D 
022140 023725 001566 00886. I OUTPUT 
014124 014251 000126 00086. D 
MAINMEO.TSK;1 Memory allocation map TKB M40.10 Page 2 
MAINO 14-MAR-83 16:01 
*x**k*k Root segment: MAINO 
R/W mem limits: 000000 023135 023136 09822. I-Space 

000000 014123 014124 06228. D-Space 
Disk blk limits: 000002 000024 000023 00019. I-Space 

000025 000041 000015 00013. D-Space 
Memory allocation synopsis: 
Section Title Ident 
File 

BLK.:(RW,1,LCL,REL,CON) 000300 000216 00142. 
000300 000216 00142. CBTA 04.3 


SYSLIB.OLB;/7 
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INPUT 


xxx Segment: 


R/W mem 


Disk blk limits: 


x*kk Segment: 


R/W mem 


Disk blk limits: 


xxx Segment: 


R/W mem 


Disk blk limits: 


xxk Segment: 


R/W mem 


Disk blk limits: 


xxk Segment: MULL 


R/W mem 


INPUT 


022140 
014124 


000042 
000064 


022140 
014124 


000066 
000067 


022310 
014170 


000070 
000071 


022310 
014170 


000072 
000073 


022310 
014170 
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043645 
015507 


000063 
000065 


022307 
014167 


000066 
000067 


022437 
014173 


000070 
000071 


022437 
014173 


000072 
000073 


022437 
014173 


16201 


021506 
001364 


000022 
000002 


000150 
000044 


000001 
000001 


000130 
000004 


000001 
000001 


000130 
000004 


000001 
000001 


000130 
000004 
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09030. 
00756. 


00018. 
00002. 


00104. 
00036. 


00001. 
00001. 


00088. 
00004. 


00007: 
00001. 


00088. 
00004. 


00001. 
00001. 


00088. 
00004. 


Memory allocation map TKB M40.10 
14-MAR-83 


I-Space 
D-Space 


I-Space 
D-Space 


Il=Space 
D-Space 


I-Space 
D-Space 


I-Space 
D-Space 


I-Space 
D-Space 


I-Space 
D-Space 


l=Space 
D-Space 


I-Space 
D-Space 


Page 4 


Page 5 


Page 7 


Page 8 


Page 9 
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Disk blk limits: 000074 000074 000001 00001. 


000075 000075 000001 00001. 


I-Space 
D-Space 


MAINMEO.TSK;1 Memory allocation map TKB M40.10 Page 10 
DIVV 14-MAR-83 16:01 
xxx Segment: DIVV 
R/W mem limits: 022310 022441 000132 00090. tI-Space 
014170 014173 000004 00004. D-Space 
Disk blk Limits: 000076 000076 000001 00001. tI-Space 
000077 000077 000001 00001. D-Space 
Page 11 
kkk Segment: OUTPUT 
R/W mem limits: 022140 023725 001566 00886. I-Space 
014124 014251 000126 00086. D-Space 
Disk blk limits: 000100 000101 Q00002 00002. I-Space 
000102 000102 000001 00001. D-Space 
Memory allocation synopsis: 
Section Title Ident 
File 
BLK.:(RW,1,LCL,REL,CON) 022140 000374 00252. 
022140 000042 00034. SAVAL 00 
SYSLIB: OLB? 
022202 000074 00060. CATB 03 
SYSLIB.OLB; / 
022276 000126 00086. CDDMG 0Q0 
SYSLIB.OLB; 7 
022424 000110 00072. C5STA 02 
SYSLIB.OLB;/7 


Example 13: 


In this example, the segment table for task 
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Note that the segment table corresponds exactly to the overlay 
description list given in the Task Builder map. The sequence of 
ZAP commands is as follows: 


NOTE 


This example was taken from a PDP-11 running 
RSX-11M-PLUS. The example serves to show users 
how to use ZAP. Note, however, that I and D 
Space capability is not currently supported. 


ZAP>MAINMEO/LI 

ZAP Version V02.01 COPYRIGHT (c) DIGITAL EQUIPMENT 
CORPORATION 1983 

Segment Table 

000002: Q00000-022137 MAINO I-space root 
000025: Q00000-014123 MAINO D-space root 
000042: 022140-043647 INPUT I- and 

000064: 014124-015507 INPUT D-space 


000066: 022140-022307 CALC I- and 
000067: 014124-014167 CALC D-Sspace 
000070: 022310-022347 AADD I- and | 
000071: 014170-014173 AADD D-space 
000072: 022310-022437 SUBB I- and 
000073: 014170-014173 SUBB D-space 
000074: 022310-022437 MULL I- and 
000075: 014170-014173 MULL D-space 
000076: 022310-022443 DIVV I- and 
000077: 014170-014173 DIVV D-space 


000100: 022140-023727 OUTPUT I- and 
000102: 014124-014253 OUTPUT D-space 


In Example 1, the first command line invokes ZAP and the second 
command line requests the segment table for the task MAINMEO. 
The /List switch directs ZAP to give the starting disk block for 
the root segment of the task (in this example, MAINO) and for 
each segment overlaid on the root of the task. The /List switch 
also lists the base and top addresses, plus the segment text 
string for each segment. 


Because this is an I- and D-space overlaid task, there is an 
I-space root segment and a D-space root segment and each is a 
part of the root segment of the task MAINO. In this example, the 
I-space root segment begins at disk block 2. The addresses for 
the I-space root segment range from 000000 to 022137. The next 
line of numbers is for the D-space root segment which begins at 
disk block 25. The addresses for the D-space root segment range 


from 000000 to 014123. The next line of numbers is for the 
segment INPUT. That I-space segment begins at disk block 42 and 
the D-space segment begins at disk block 64. The I-space 


addresses range from 022140 to 043647 and the D-space addresses 
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range from 014124 to 015507. The table continues 
remaining overlaid segments in the task MAINMEO. 


for the 


Example 2: 


In this example, the contents of a location in another task 
module (TEST.MAC) are being changed. The following excerpt from 
the module shows the associated code. 


TEST - TEST MACRO FILE MACRO M1113 18-MAR-81 07:48 PAGE 8-1 


1269 ,; THIS IS A PART OF THE MODULE 
1270 : TEST .MAC 

1271 ; WHICH IS IN THE ROOT SEGMENT: 
PAS : TEST 

1273 ; 

1274 010132 010146 MOV R1,-(SP) 
1275 010134 012704 041114 MOV #"LB,R4 
1276 010140 005003 CLR R3 

1277 010142 CALL SFNDUB 
1278 010146 010146 MOV R1,-(SP) 
1279 010150 012704 050123 MOV #"SP,R4 


The sequence of ZAP commands is: 


_42:121244;0R<RET> 
_0,10136"<RET> 
042:131402" LB 


_' <RET> 
042:131402’ L 
_' <RET> 
042:131403’ B 
_120<RET> 


_0,10136"<RET> 
042:131402" LP 


The first command line loads the starting address of TEST.MAC 
(121244 in disk block 42) into Relocation Register 0. The second 
command line displays as an ASCII word the contents of location 
10136 of the module. The contents are LB. The first apostrophe 
command (’) displays the first byte of the word (L) and_ the 
second command displays the second byte (B). The following 
command line changes the contents of the second byte to 120, 
which is the ASCII code for the letter P. The last command 
displays the new contents of location 10136, which are now LP. 


Example 3: 
In this example, the contents of a location are also being 


changed. This time, the location is in the module TSTVB1.MAC. 
The following excerpt is the associated code. 
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TSTVB1 

153 

154 

155 

156 

157 000334 
158 000336 
159 000340 
160 000346 
The 


The first command line loads the starting address 
(133470 in disk block 42) 
command line displays in octal the contents of 
module. 
location from 60 to 100. 


the 


005702 
001404 
052767 
000403 


000060 


_42:133470;1R<RET> 
-1,342/<RET> 
042:134032/ 000060 
_100<RET> 

_1,342/<RET> 
042:134032/ 000100 


EXAMPLES 


- TSTVB1 MACRO FILE MACRO M1113 


LEZOLO 


sequence of ZAP commands is: 


into Relocation Register 1. 


18-MAR-81 07:52 PAGE 4-2 


: PART OF MODULE TSTVB1.MAC 
; WHICH IS ALSO IN THE ROOT SEG 


' TEST 
TST R2 
BEQ 70$ 
BIS #60,SR3 
BR 75S 


of TSTVB1.MAC 
The second 


location 342 in 


The third command line changes the contents of this 


contents (again in octal). 


Example 4: 


In this example, 
instructions 


TSTCM.MAC, 


TSTCM - TSTCM MACRO FILE 


402 
403 
404 
405 
406 
407 


The 


The last command line displays the 


the operation code (op 
in another module is being changed. 
and the following excerpt is the associated code. 


MACRO M1113 


new 


one of the 
The module is 


code) for 


; PART OF THE MODULE TSTCM.MAC 
; WHICH IS IN THE SEGMENT: TSTCM 


001272 
001276 
001302 


sequence 


073127 
010037 
062701 


of ZAP 


_113:154530;R2<RET> 


_2,1302/<RET> 


113:156032/ 062701 


_162701<RET> 
_2,1302/<RET> 


113:156032/ 162701 


177766 


00000G 


140002 


commands 1S: 
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18-MAR-81 07:47 PAGE 3-7 
ASHC #—-10.,R1 
MOV RO, @#KISAR6 
ADD #140000+2,R1 


EXAMPLES 


x 

The first command line loads the starting address of TSTCM.MAC 
(154530 in disk block 113) into Relocation Register 2. The 
second command line displays in octal the current instruction 
contained in location 1302. The instruction includes the op code 
06 for the ADD operation. The third command line changes the op 
code to 16, which signifies the SUBTRACT operation. The fourth 
command line displays the new contents of the location and the xX 
command ends the ZAP session. 


10.8 ZAP ERROR MESSAGES 

This section lists the messages generated by ZAP, explains’ the 
condition that causes each message, and suggests a response to 
the message. 


ZAP -- ADDRESS NOT WITHIN SEGMENT 


Explanation: The address specified was not within the 
overlay segment specified. 


User Action: Reenter the command line, specifying the 
correct address or overlay segment number. 

ZAP -- CANNOT BE USED IN BYTE MODE 
Explanation: The at sign (@), underscore (_), and right 
angle bracket (>) commands cannot be used when a location is 


opened as a byte. 


User Action: If the location is an even address, open the 
location as a word. 


ZAP -- ERROR IN FILE SPECIFICATION 
Explanation: The file specification was entered 
incorrectly. 


User Action: Reenter the command line, using the correct 
file specification. 
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ZAP -- ERROR ON COMMAND INPUT 


Explanations An I/O error occurred while a command line was 
being read. This could be a hardware error. 


User Actions: Ensure that the hardware is functioning 


properly. If it is, reenter the command line. If not, call 
your DIGITAL Customer Support Center. 


ZAP -- I/O ERROR ON TASK IMAGE FILE 


Explanation: An I/O error occurred while the file being 
modified was being read or written. This could bea 
hardware error. 


User Actions: Ensure that the hardware is functioning 
properly. If it is, reenter the command line. If not, call 
your DIGITAL Customer Support Center. 

ZAP -- NO OPEN LOCATION 


Explanations You attempted to modify the contents of a 
closed location. 


User Action: Open the location to perform the modification. 
ZAP -- NO SUCH INTERNAL REGISTER 


Explanation: The character following a dollar sign was not 
a valid specification for the internal register. 


User Action: Reenter the command line, specifying the 
correct value. 


ZAP -- NO SUCH RELOCATION REGISTER 


Explanation: An invalid number was specified for a 
Relocation Register. 


User Action: Relocation Registers are numbered 0 through 7. 


Any other numbers are illegal. Reenter the command line, 
specifying a valid Relocation Register number. 
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ZAP -- NO SUCH SEGMENT 


Explanation: The starting disk block was not the start of 
any segment in the task image file on disk. 


User Action: Reenter the command line, specifying the 
correct disk block address. 

ZAP-- NOT A TASK IMAGE OR NO TASK HEADER 
Explanation: An error occurred while the segment tables 
were being constructed. Possibly, the file is not a task 
image, the /AB switch was not specified, or the task image 
is defective. 
User Action: Terminate the ZAP session, then try invoking 
ZAP with the /AB switch specified. 


ZAP -- NOT IMPLEMENTED 


Explanations: You entered a command that is recognized by 
ZAP, but not implemented. 


User Action: Ensure that you entered the command correctly. 


ZAP -- OPEN FAILURE FOR TASK IMAGE FILE 


Explanation: The file to be modified could not be opened. 
Possibly, the file does not exist, the file is locked, the 
device is not mounted, or you do not have write-access to 
the file. 


User Action: Check the file specification for errors, or 
check your file access privileges. Refer to Section 3.23 
for an explanation of the DIRECTORY command and the /FULL 
qualifier. | 


ZAP -- SEGMENT TABLE OVERFLOW 


Explanation: ZAP does not have enough room in its partition 
to construct a segment table. 


User Actions: You cannot use ZAP on the file. 
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ZAP -- TOO MANY ARGUMENTS 


Explanation: You entered more arguments on the command line 
than are allowed. 


User Actions: Reenter the command line, specifying the 
correct syntax. 

ZAP -- UNRECOGNIZED COMMAND 
Explanation: ZAP did not recognize the command as entered. 
User Actions Check the syntax of the command you are trying 
to execute, then reenter the command line, specifying the 
correct syntax. 

ZAP -- VERIFY FAILURE 
Explanation: The V command determined that the contents of 
a location did not match the expected value. ZAP 


terminates. 


User Actions: If applicable, check for errors in the 


indirect command file. Ensure that the contents of the file 
are what they should be. Locate the cause of the error. and 
reenter the command line. Ensure that you are correcting 


the right file or file version. 
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CHAPTER 11 
SOURCE LANGUAGE INPUT PROGRAM (SLP) 


The Source Language Input Program (SLP) is a utility used to 
maintain and audit source files. The optional audit trail in the 
output files allows you to keep a record of maintenance changes. 


SLP is invoked by edit command statements and switches. SLP edit 
command statements allow you to: 


@ Update (delete, replace, add) lines in an existing file 


@® Create source files 


® Run indirect files containing SLP edit commands 


Input to SLP is a file that you want updated and command input 
consisting of text lines and edit command lines that specify the 
update operations to be performed. To locate lines to _ be 
Changed, SLP uses line numbers’ or character strings that you 
Specify. Command input can come directly from your terminal or 
from an indirect command file containing commands and text lines 
to be inserted into the file. SLP accepts data from any FILES-11 
volume. 


Output from SLP is a listing file and the updated input file. 
SLP provides an optional audit trail that helps you keep track of 
the update status of each line in the file. If an audit trail is 
not suppressed, it is shown in the listing file and permanently 
applied to the output file. 


You can control SLP processing with SLP control switches. These 
Switches allow you to: 


@ Suppress audit trails 


e Specify the length and beginning position of the audit trails 


1i-1 


@e Calculate the checksum value for the edit commands 


@ Generate a double-spaced listing 


To invoke SLP type: 
EDIT/SLP (refer to EDIT/SLP In Chapter 3) 
OT 
S RUN $SLP 
SLP will prompt: 
SLP> 
You should not specify TI: as your output file, because when you 


finish editing, you will not have a copy of the output file and 
the input file will be the same as before you began editing. 


11.1 SLP INPUT AND OUTPUT FILES 


SLP requires two types of input, an input file and command input. 
The input file is the source file you want to update using SLP. 
Command input consists of SLP edit commands and, optionally, new 
lines of text to be placed in the file. 


SLP output consists of an output file and a listing file. The 
output file is the updated input file. The listing file is a 
copy of the output file with line numbers added. Both show the 
changes SLP made to the file. 


11.1.1. The Input File 


The input file is the file to be updated by SLP. It can contain 
as many lines of text as are required. When SLP processes the 
input file, it makes the changes specified by SLP edit commands. 
If an audit trail is generated, these changes are noted in the 


output files. 


11.1.2 Command Input 


SLP uses command input to update files. Command input can be 
entered interactively after you invoke the SLP utility or 
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indirectly by means of indirect command files. 


You enter command input to SLP in two modes: command mode and 
edit mode. After it is invoked, SLP is in command mode, where 
the first line entered must be the command line defining the 
Files to be processed. When SLP accepts this line, it 
initializes the files you want processed. Once these files are 
initialized, SLP enters edit mode, where it interprets the lines 
you enter as SLP edit commands or new input lines. 


You terminate command input with a single slash as the first 
Character of an edit command line. 


The following example shows the general form of command input: 
MYPILE.MAC;2/CS/AU:55:10,MYFILE.LST;1=MYFILE.MAC;1 


-3,,/;BI007/ 
CMP (R1)+,B 


-4,4 

DEC- RZ 

i 

NOTE 

Numeric values given for switches default to 
OCtal. Decimal values must be followed by a 
period (.). The default position for the audit 
trail is 80 (decimal) and its default length is 8 
(decimal); no more than 14 (decimal) characters 


may be specified. 


The first line is the command line, where you define the output 
file, the listing file, and the input file. The next four lines 
comprise the SLP edit commands and input lines. 


Note that the input and output files in the example have the same 
file name and file type; only the versions are different. To 
ensure that the correct files are processed, specify the version 
numbers explicitly when you enter the SLP command line. 
Wildcards cannot be used in any of the file specifications. 


You can also calculate the checksum value for the edit commands. 
Specify the checksum switch with either the input or output file 
specification in the format: 


/CS[3:n] 
The checksum value can be calculated for all SLP edit command 
lines. The checksum value cannot be calculated for the 
following: 
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e The command line specifying the input and output files. 
@e Comments in the edit command lines. 


@e <Any spaces and/or tabs between characters included in the 
checksum calculation and those characters excluded from the 
calculation. 


@ The second comma and anything following it in an edit command 
line (that is, audit trail and/or comment). 


@e Comment delimiter (specified by the first character of the 
last audit trail string before the current delimiter) and any 
Characters following it in an input line, whether or not it 
is being used in the line as a delimiter. The value is then 
reported in a message on your terminal. If you specify a 
value for the checksum and it is not the same as the 
calculated checksum, you will get a diagnostic error message. 


11.1.3 The SLP Listing File 


The SLP listing file shows the updates made to the source file. 
Each line in the listing file is numbered. Updates are marked by 
means of the audit trail if one has been generated. The examples 
given throughout this chapter contain samples of listing files. 


11.1.4 The SLP Output File 


The SLP output file is the updated input file. All of the 
updates specified by command input are inserted in this file. 
The audit trail, if specified, is applied to lines changed by the 
update. The audit trail is included in the output file. The 
numbers generated by SLP for the listing file do not appear in 
the output file. 


11.2 HOW SLP PROCESSES FILES 


This section describes how SLP porcesses files when it receives 
the following command line and edit commands. 


MYFILE.MAC;2/AU:55:10,MYFILE.LST/-SP=MYFILE.MAC;1 
-3 

CMP (R1)+,B 

-4,4 
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DEC (R2) 
/ 


This is the input file (MYFILE.MAC;1) before SLP processes’ the 
files: 


MOV #BUF1,RO 
MOV #SIZ,R1 

CALL READ 

TST R2 

BEQ END 

CLR R1 

MOV R2,NUMC 

CMPB (RO)+,A 

BNE 20S 

INC Ri 


The following is the listing file (MYFILE.LST;1) resulting from 
SLP processing of these files: 


The audit trail shows the new lines (;**NEW**) 
have been removed (;**-1). (The 


where lines 


not suppressed 


1. MOV #BUF1,R0 

2. MOV #SIZ,R1 

3. CALL READ 

4. CMP (R1)+,B > *kKNEW* * 
5. DEC (R2) ; **NEW** 
6. BEQ END sk 

7. CLR R1 

8. MOV R2,NUMC 

9. CMPB (RO)+,A 
10. BNE 20$ 
11. INC R1 


audit trail generation or if 


and indicates 
audit trails 
;**NEW** and ;**-n are automatically generated by SLP if you have 


you have 


not 
has 


specified another audit trail string.) In this case, a_ line 
been added after line 3, and line 4 has been deleted and a new 
line added in its place. 


SLP processes an input file using command input. When processing 
begins, SLP writes each line from the input file into the output 
file until it reaches a line to be modified, as requested in the 
command input. When SLP reaches a line to be modified, it 
modifies the line, notes the change by means of the audit trail, 
and then continues writing lines to the output file until another 
command is encountered or until end-of-file is reached. 
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11.3. USING SLP 

This section describes how to: 

@e Specify the SLP edit commands. 

@ Update files using the SLP edit commands. 


@ Enter SLP commands interactively and by means of indirect 
command files. 


@e Create a source file using SLP. 


11.3.1 Specifying SLP Edit Commands 


The SLP edit commands allow you to update source files by adding, 
deleting, and replacing lines ina file. SLP allows you to enter 
lines sequentially. Once past a given line in the file, you 
cannot return the line pointer to that line. To return the line 
pointer to that line, you must begin another SLP editing session. 
You enter SLP edit commands after invoking SLP and specifying an 
edit command line. 


The general format of the SLP edit command line is as follows: 


-{locator1i]{,locator2][,/audittrail/][{; comment] 
inputline 


- (dash) 
Identifies a SLP edit command line. 

locatorli 
A line locator that causes SLP to move the current line 
pointer to a specified line. If you specify only locatori, 
the current line pointer is moved to that line and SLP reads 
the next line in the command input file. This field can be 
specified using any of the locator forms described later in 
this section. 

locator2 
A line locator that defines a range of lines (that is, the 


range beginning with lJlocatori and ending with locator2, 
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inclusive) to be deleted or replaced. This field can be 


specified using any of the locator forms described later in 
this section. 


faudittrail/ 


A character string used to keep track of the update status 
of each line in the file. The string must be enclosed 
within slashes (/). It consists of a comment delimiter as 
the first character and then a text string. The semicolon 
(;) 1s the default delimiter for audit trails automatically 
generated by SLP (;**NEW** and ;**-n). The comment 
delimiter specified in audittrail (usually a semicolon) is 
the new delimiter for all subsequent audit trails until 
redefined by a later audittrail. 


inputline 
A line of new text to be inserted into the file immediately 
following the current line. You can enter as many input 
lines as required. 


comment 


A line of text (delimited by a semicolon) at the end of the 
SLP edit command line that appears only in the command input 
file. 


All fields in the SLP edit command line are positional and commas 
must be specified. 


The locator fields can take one of the following forms: 
-/string/[+n] 
-/string...string/[+n] 
-number([+n] 
-.f{+n] 


string 


A string of ASCII characters. SLP locates the line where 
the string exists and moves the current line pointer to that 


line. If the locator is specified in the form 
/string...string/, SLP locates the line where the _ two 
character strings delimit a larger character string 


abbreviated by an ellipsis (...). 
number 
A decimal line number where the current line pointer is_ to 


be moved. The largest line number that can be specified is 
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9999. 
- (period) 


The current line. 


A decimal value used as an offset from the line specified by 
the locator. You cannot use +n by itself. It must be 
specified with a number or string locator or a period. SLP 
moves the current line pointer n IJlines beyond the line 
specified in the locator field. 


Although the values for number and n are taken as _ decimal, 
remember that all other SLP values are octal by default. 


All forms of the line locator can be specified interchangeably in 
the SLP edit command lines. 


11.3.2 Entering SLP Edit Commands 


Once you have invoked SLP, you can enter SLP edit commands 
interactively or by specifying indirect command files. In both 
cases, the first command you must enter is the command line 
defining the files to be processed during this SLP session. This 
section gives examples of how to use both methods of entering SLP 
commands. 


The following file (BASE.MAC;1) is used as the input file for the 
examples in this section: 


MOV #SSWTCH,R3 

CLR SERFLG 

CLR SCRCVL 

CLR SCSSV 

MOV SPSAV,SP 

MOV #SCFNMB, RO 

MOV # <SHDSIZ-SCFNMB>/2+1,R1 
CLR (RO)+ 

DEC R1 

BNE 55 


11.3.2.1 Entering SLP Commands Interactively - To alter the 
example file interactively, invoke SLP. Once you have entered 
the SLP command mode, SLP does not display prompts. The first 
line you enter must always be the command line defining the files 
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you want processed during this session: 


BASE.MAC;2/AU: 48./TR,BASE.LST=BASE.MAC;1 


Then you enter the edit commands and input lines: 


-3 

TST Ri 
-4,4 

BEQ 10$ 
-6,,/;I5M010/ 
CLR R2 

ys 


In this example, the edit commands instruct SLP to do the 
following: -3 inserts a new line after line 3; -4,4 deletes line 
4 and replaces it with a new line; -6,,/;JM010/ inserts a line 
after line 6 with a new audit trail value. 


When you have entered all the corrections, enter the slash (/) to 
terminate the edit session. SLP processes the files and returns 
control to you with the prompt: 

SLP> 


This returns SLP to command mode. You can then enter another 
input file and begin another editing session. 


The listing file (BASE.LST;1) resulting from SLP processing 
appears as follows: 


1. MOV #SSWTCH,R3 

25. CER SERFLG 

3. CLR SCRCVL 

4. TST R1 ek kKNEWX** 
5. BEQ 105 -k KNEW * 
6. MOV SPSAV,SP kk 1 

7. MOV +SCFNMB, RO 

8? CLR R2 > JM010 
9. MOV #<SHDSIZ-SCFNMB>/2+1,R1 

10. CLR (RO)+ 

14:3.. ‘DEC R1 

12. BNE 5$ 


The /TR switch (/TR in the command line) records the truncation 
of lines by the audit trail. In the listing file, a question 
mark (2?) replaces the period (.) after the line number for the 
lines that were truncated. It is possible that audit-trail 
strings in the input file will be truncated by the new 
audit-trail string, although the commands or text strings will 
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not be truncated. 


11.3.2.2 Entering SLP Commands Using Indirect Command Files 

- To alter the example file by using the SLP edit commands in 
the indirect command file, BASE.SLP, you invoke SLP and _ SLP 
responds with the prompt: 


oLP> 


You then enter the file specification for the indirect command 
file containing the command line, the SLP edit commands, and the 
input lines: 


@BASE.SLP 


SLP processes the files just as if you entered the commands’ and 
input lines interactively, returning control to you with the 
prompt: 


SLP> 


The output listing resulting from indirect command file 
processing is exactly like the output listing resulting from the 
same changes made interactively. 


Indirect command files can be nested to .. maximum level of three. 
This permits indirect command files to reference a text file. 


11.3.2.3 Using SLP Operators - In addition, you can enter 
special characters called operators, which perform. specific 
functions. Table 11-1 lists the operators and the function each 
performs. Enter operators, in edit mode, as the first character 
of an input line. 


Table 11-1: SLP Operators 


Operator Function 


~ Identifies the first character of a SLP edit 
command line. 


x Suppresses audit-trail processing. 
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% Reenables audit-trail processing. 

@ Invokes an indirect command file for SLP 
processing. 

/ Terminates the SLP edit session, and then returns 


to SLP command mode. 


< Enables you to enter characters in the input file 
that SLP otherwise would interpret as operators. 
For example, </ hides the slash character from 
SLP, thereby enabling you to enter the slash into 
the output file without terminating the SLP 
editing session. This character can be used with 
all SLP operators. 


11.3.3 Updating Source Files With SLP 


This section describes the procedure for generating a numbered 
listing for use in editing source files by line number. The 
section also describes how to use SLP to add, delete, and replace 
lines ina file. 


11.3.3.1 Generating a Numbered Listing - SLP processes input by 
line number. However, line numbers appear only in the listing 
file; they are not written to the output file. To use SLP 
effectively, you should use a numbered listing when you prepare 
command input. To generate a numbered listing, first invoke SLP, 
then enter the command line in the format: 


,listfile=infile 


i 


In this format, listfile is the name you assign to the listing 
file SLP will produce and infile is the name of the input file 
whose lines are to be numbered. The slash (/) terminates edit 
mode. For example, suppose the input file is: 


MOV R1,-(SP) 
BIC #177770,@SP 
ADD #60,@SP 
MOVB (SP)+,-(RO) 
ASR Ri 

ASR Ri 

ASR Ri 
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DEC R2 
BNE 30S 
MOV #MSG,RO 


SLP processes each line to generate a numbered list file (list 
file;1): 


1. MOV R1,-(SP) 
2. “BLE #177770,@SP 
3. ADD #60,@SP 
4,  MOVB (SP)+,-(R0) 
5. ASR R1 
6. ASR R1 
7. ASR R1 
8. DEC R2 
9. BNE 30S 
10. MOV #MSG,RO 


11.3.3.2 Adding Lines to a File - The three SLP edit command 
formats for adding lines to a file are: 


-locator1 
inputline 


or 


=locatorl » 5 
inputline 


or 


locatori,,/audittrail/ 
inputline 


The following example shows how to add lines to ae file. The 
command input consists of the following lines: 


MYFILE.MAC;2/AU:48.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;1 
=3 
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CMP (R1)+,B 
-4,4 

DEC R2 

-6, ’ pf FIMOLO/ 
INC R3 

oO ¢/ -BIV0G/ 
BEQ 10$ 

7 


The next example uses text rather than line numbers 
where new lines should be added or deleted: 


to indicate 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 


-/BEQ/ 
CALL 


/ 


In this example, 


SLP processing 
(MYFILE.LST;1): 


MOV 
MOV 
CALL 
TST 
BEQ 
CALL 
CLR 
MOV 
CMPB 
BNE 
INC 


Powe Oy hAM & WN FE 


bh 


SLP has numbered 
following line 
string BEQ. 


The next example 
command lines: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE. 


-/#SIZ/+2 
CMP 
/ 


WRITE 


the edit command /BEQ/ instructs SLP to insert a 
line after the line with the first occurrence of BEQ. 


generates the 


#BUF1,RO 
#SIZ,R1 
READ 

R2 

END 
WRITE 
R1 
R2,NUMC 
(RO)+,A 
20$ 

Ri 


the lines and applied an 
5, where SLP found the 


uses the same input file 


(Rija58 


following 


listing File 


» kkKNEW** 


audit trail to the line 
first occurrence of the 


and the following new 


MAC;1 


SLP processing generates the following listing file (MYFILE;1): 


1. MOV 
2. MOV 


#BUF1,R0 
#S1IZ,R1 
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2.- “CALL READ 

4, TST R2 

S. CMP (R1)+,;B > * KNEW * 
6. BEQ END 

i. CLR R1 

8. MOV R2,NUMC 

9. CMPB (RO)+,A 
10. BNE 20$ 

11. ING R1 


Again, SLP has numbered the lines and this time the new input 
line is inserted so that it is two lines beyond the line 
containing the first occurrence of the string /#SIZ/. 


11.3.3.3 Deleting Lines from a File - The SLP edit command 
format for deleting lines from a file is: 


-~{locatori],[{locator2],[{/audittrail/][; comment] 


In this format, locator1i and locator2 can be any of the forms of 
the locator fields described in Section 11.3.1; locatori 
specifies the line where SLP is to begin deleting lines; locator2 
specifies the last line to be deleted. SLP deletes all lines 
from locatorl through locatorz, inclusive. 


Suppose an input file consists of the following lines: 


MOV #BUF1,RO 
MOV #S1IZ,R1 
CALL READ 

TST R2 

BEQ END 

CLR R1 

MOV R2,NUMC 
CMPB (RO)+,A 
BNE 205 

INC R1 


To delete lines from the file, the command input can consist of 
the following commands and text lines: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 
-~-/MOV...R1I/, /NUMC/ 
A 


SLP processing generates the following listing file (MYFILE;1): 


1. MOV 4#BUF1,RO 
2. CMPB (RO)+,A 
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3. BNE 205 
4. INC R1 ,x*k-6 
In this example, the ellipsis (...) abbreviates the larger string 


MOV #SIZ,R1. Assuming the two strings bracket a larger string, 
SLP searches for the first occurrence of the string MOV and then 
the first occurrence on the same line of the string Ri, in this 
case the string MOV #SIZ,R1. SLP begins deleting lines at this 
line and continues deleting lines until it deletes the last line 
of the given range, specified here by the string NUMC. SLP 
applies the audit-trail count of the lines it deleted to the next 
line from the input file. 


Using the same input file as used in the previous example, the 
following example shows how to delete a single line using the 
period locator. The command input for this example is: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 
-/MOV #SIZ,R1/,. 
7 


SLP processing generates the following listing file (MYFILE;1): 


1. MOV #BUF1,R0 

23 “CAGE READ sk 1 
3. TST R2 

4. BEQ END 

5S. CLR R1 

6. MOV R2,NUMC 

7.  CMPB (RO)+,A 

8. BNE 20$ 

9. INC R1 


SLP moves the current line pointer to the line containing the 
string MOV #SIZ,R1 and then finds the period as the second 
locator field. Since the second locator field is specified as 
the current line, SLP deletes the current line. 


11.3.3.4 Replacing Lines in a File - A replacement is the 
deletion of old text followed by the insertion of new text. The 
number of lines deleted need not match the number of lines added. 
To replace lines in a file, use the same SLP edit command format 
as used in the delete command. The first line locator field 
specifies the first line to be deleted. The second line locator 
field defines the last line in the range to be deleted and where 
the new text is to be inserted. For example: 


~4,.+4 
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This command instructs SLP to move the line pointer to line 4, 
and replace line 4 and the next four lines with new input lines. 


The following example shows how to delete lines from a file and 
replace them with new lines. The input file consists of the 
following lines: 


MOV #BUF1,RQ 
MOV #SIZ,Ri 
CALL READ 
pinoy R2 

BEQ END 

CLR Ri 

MOV R2,NUMC 


The command input is: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 


~2,.+1 
CMP (R1)+,B 
INC R2 
a 
In this example, the edit command, -2,.+1, instructs SLP_ to 


delete lines 2 and 3 and insert two new lines. 


SLP processing generates the following listing file (LISTING;1): 


1. MOV #BUF1,RO 

2. CMP (R1)+,B ; *kKNEW* * 
3. INC R2 ; *KNEW* * 
a.. TST R2 okk-2 

5. BEQ END 

6. CLR R1 

7. MOV R2,NUMC 


11.3.4 Creating Source Files Using SLP 

Using SLP to create source files is possible, but not 
recommended. SLP does not have an intraline editing mode and you 
cannot return to a line once you have passed it. An interactive 
editor, EDT, is better for creating source files. 


To create source files using SLP, invoke SLP and enter’ the 
command line in the format: 


outfile/-AU[/sw][,listfile][/sw]l=[primary_input_device:[/sw] ] 
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outfile 


The file specification for the output file. The default 
device is SY0:. 


/-AU 
Specifies that an audit trail is not to be generated. 
Otherwise, you will get the ;**NEW** audit trail on every 
line of the output files. 

listfile 


The file specification for the listing file (optional). The 
default device is implied by the output file specification. 


primary _input_device: 
Specifies that input for the file being created is coming 
from this device, for example, a terminal. The default 
device is your primary input device. 

/SW 


Specifies any optional SLP switches. 


The following file specification creates a new file called 
MYFILE.MAC from the terminal and puts it on SyY0:. 


MYFILE.MAC/-AU=TI: 
Once you have entered the file specification, SLP accepts each 
line aS a variable-length record of up to 132 (decimal) 
Characters. Trailing blanks and tabs on input lines are deleted. 


SLP expects input to the file to come from the primary input 
device. End the SLP session with a slash (/) and then a CTRL/Z. 


11.4 CONTROLLING SLP 
The SLP switches allow you to calculate the checksum value for 


the edit commands and to control the generation and format of the 
listing file and the output file. 


11.4.1 SLP Switches 


SLP output consists of two files--a listing file and the output 
file, which is the modified version of the input file. You can 
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use the SLP switches to control the audit trail and print options 
associated with the two files. 


The effects of SLP switches are the same whether you apply them 
to input or output files. Table 11-2 lists the SLP switches and 
gives a brief description of the functions each performs. 


Table 11-2: 


Switch 


/AU 


/-AU 


/BF 


/-BF 


/CM[ :n] 


FCS{[ st 


Switch 


/DB 
/-DB 


/TR 


SLP Switches 


Function 


Allows you to generate an audit trail or suppress 
audit-trail generation and specify the beginning 
field and length of the audit trail. /AU is the 
default value. See the following sections for more 
information about the /AU switch. 


Positions the audit trail by inserting spaces 
instead of tabs at the end of text information. /BF 
is the default value. 


Deletes audit trails and any trailing spaces or tabs, 
and truncates the text at a specified horizontal 
position. The value given for the beginning position 
of the audit trail is the default value for this 
Switch. 


Calculates the checksum value for the edit commands. 
If you do not specify n, SLP reports the value ina 
message on your terminal. If you do specify n and 
the checksum value that SLP calculates is not the 
Same as the one you specified, SLP displays a 
diagnostic error message. 


Function 


The procedure SLP uses to calculate the checksum 
value for the edit commands is described in Section 
fia ys ee ae 


Generates the listing file in double-space 
format. /-DB is the default value. 


Reports truncation of lines by the audit trail. EE 
line truncation occurs, you will get a diagnostic 
error message. There is no default value for this 
Switch. 
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In the listing file, a question mark (?) replaces the 
period (.) in the line number of the lines that were 
truncated. 


/5Q Sequences the lines in the output file so that the 
numbers reflect the line numbers of the original 
input file. New lines added to the file have _ the 
same number as the preceding line. This allows the 
MACRO Relocatable Assembler to output listing files 
that contain the original line numbers, thus easing 
the process of updating correction files. 


If you specify a listing file, SLP preserves the line 
numbers of the input file but does not display 
numbers for the new lines that have been inserted. 


/RS Resequences the lines in the output file so that’ the 
line numbers are incremented for each line written to 
the output file. The /RS switch overrides the /SQ 


Switch. 

/NS Does not sequence the lines in the output file. New 
lines are indicated by the audit trail (if 
specified). The /NS switch is the default condition 


and overrides the /SQ and /RS switches. 


11.4.2 Controlling the Audit Trail 


The /AU switch allows you to generate, suppress, and set’ the 
length and contents of the audit trail. To suppress generation 
of the audit trail, specify the /-AU switch in either the input 
Or output file specification. For example, either of the 
following command lines generates an output file with no audit 
trail: 


DW1:MYFILE.MAC;3/-AU,MYFILE.LST:=MYFILE.MAC;2 
DW1:MYFILE.MAC;3,MYFILE.LST:=MYFILE.MAC;2/-AU 
By default, SLP automatically generates an audit trail; that is, 
you need not explicitly specify the /AU switch in your command 


line (unless you want to specify the beginning position and 
length of the audit trail). 
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11.4.3. Setting the Position and Length of the Audit Trail 


You can set the beginning position of the audit trail and _ the 
length of the audit trail using the /AU switch in the format: 


/AU: position:length 
position 


A number, less than or equal to 132 (decimal), designating 
the beginning character position of the audit trail on the 
line. SLP rounds this value to the next highest tab stop (a 
multiple of 8). The default value for position is 80 
(decimal). 


NOTE 


Numeric values given for switches default to octal. 
Decimal values must be followed by a period (.). 
The default position for the audit trail is _ 80 
(decimal) and its default length is 8 (decimal); no 
more than 14 (decimal) characters may be specified. 


length 


The length of the audit trail. The default value for length 
is 8 (decimal) characters; no more than 14 (decimal) 
characters may be specified. 


The following example shows how to specify the beginning position 
and length of the audit trail. The input file for this example 
1S: 


MOV #BUF1,RO 
MOV #SIZ,R1 
CALL READ 

TST R2 

BEQ END 


The command input is: 


MYPILE.MAC;2/AU:30.:10./TR,MYFILE.LST=MYFILE.MAC;1 
-2,.+1,/;CHANGE001/ 


CMP (R1)+,B 
DEC R2 
a 


The listing file MYFILE.LST;1 resulting from SLP processing is: 


1. MOV #BUF1,RO 
2. CMP (R1L)+,B > CHANGE001 
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3. DEC R2 ; CHANGE001 
4. TST R2 pee? 
5. BEQ END 


11.4.4 Changing the Value of the Audit Trail 
To change the value of the audit trail, specify: 
-{locatori],{locator2],/;new value/ 


The following example shows how to change the audit trail values. 
The input file consists of the following lines: 


MOV #BUF1,RO 
MOV #SIZ,R1 
CALL READ 

TST R2 

BEQ END 

CLR R1 

MOV R2,NUMC 
CMPB (RO)+,A 
BNE 20$ 

INC R1 


The command input consists of the following commands and text 
lines: 


MYFILE.MAC;2/AU:48.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;1 


-3 

CMP (R1i)+,B 
-4,4 

DEC R2 
-6,,/;IM010/ 
INC R3 
-9,,/;BI008/ 
BEQ 10$ 

A 


In this example, the edit commands instruct SLP to insert a_ line 
after line 3, to delete and replace line 4, and to insert new 
lines after lines 6 and 9 with new audit trail values. 


The listing file (MYFILE.LST) resulting from SLP processing 
appears as follows: 


1. MOV #BUF1,RO 

2. MOV #SIZ,R1 

3. CALL READ 

4. CMP (R1)+,B 7, S ENEWS* 
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5S. DEC R2 > x kNEW** 
6. BEQ END kk — 41 
7. CLR Ri 
8. INC R3 > JMO010 
9. MOV R2,NUMC 
10.  CMPB (RO)+,A 
11. BNE 20$ 
12. BEQ 10$ ;BJ008 
13. INC R1 


11.4.5 Temporarily Suppressing the Audit Trail 


You can temporarily suppress the generation of the audit trail by 
using the backslash (\) operator. You can then reenable 
audit-trail processing with the percent Sign (%) operator. (You 
cannot enable audit trail processing with this operator if you 
have specified the /-AU switch in the SLP command line.) 


Both operators are entered in the command input. The backslash 
(\) is specified in column 1 of the line that precedes those 
commands and/or input files for which you do not want audit-trail 
processing. The percent sign (%) is specified in column 1 of the 
line that precedes the lines for which you do want processing. 
For example: 


BAK.MAC;26/AU/-BF=BAK.MAC;25 


-~2,2 
.IDENT /05.03/ 
-23,23 
> VERSION 05.03 
OT hy 
; J. MATTHEWS Li-NOV-380 
; JMOT4 CORRECT OUT-OF-BOUNDS CONDITION FOR 
INPUT-BUFFER 
? oe fa 
~106,106,/;JM011/ 
CMP 4#i32.;R3 ° IS INPUT-BUFFER SIZE IN RANGE? 
Bhd 305 e EP “Bos. INO 
va 
The lines between the backslash (\) and the percent sign (%) are 


not affected by audit-trail processing. The lines following the 
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percent sign (%) are affected. 


11.4.6 Deleting the Audit Trail 


The /CM switch allows you to delete audit trails and trailing 
Spaces and tabs from ae file. The /CM switch applied to the 
output or input file specification accepts a numeric argument 
that specifies the beginning position of an audit trail or other 
text string to be deleted. The default for this argument is’ the 
position argument given for the /AU switch (or its default, 
decimal 80). This value is rounded to the next highest tab stop 
before use. 


When processing an input line, SLP first truncates the text to 
the next highest tab stop after the position specified, and then 
deletes any trailing spaces or tabs. The remaining text is 
copied to the output file. 

The /CM switch is specified in the form: 


/CM:[n] 


A number designating the beginning character position of the 
audit trail (or other text) to be deleted. 


For example: 


SLP>SLPR11.MAC;12/CM:119.=SLPRi1.MAC;11 

/ 
In this case, the input lines are truncated to a length of 120 
(decimal) characters. The specified length is rounded up to the 
next highest tab stop and the audit trail begins at column 121 
(decimal). Trailing spaces and tabs are deleted before each line 
is copied to the output file. 


In the following example, SLP truncates input lines to the 
default position of the audit trail, column 80 (decimal). 


SLP>SLPR11.MAC;12=SLPR1i1.MAC;11/CM 
~ : 


11.5 SLP MESSAGES 


SLP messages are divided into two groups: information and error. 
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The messages and suggested responses are given in the following 
sections. 


11.5.1. SLP Information Message 
SLP -- COMMAND FILE CHECKSUM IS #####4 


Explanation: By specifying the /CS[:n] switch in the 
command line, you requested SLP to calculate the checksum 
value for the edit commands. 


User Action: This message is for your information only. No 
action is required. 


11.5.2 SLP Error Messages 


This section lists the SLP error messages. Following each 
message iS an explanation of the error and recommended user 
action to correct the error. 


SLP error messages are issued in two formats: 


e SLP followed by a dash, the type of error message, and _ the 
error message. If applicable, the command line or command 
line segment that caused the message is printed on the next 
line. For example: 


SLP -- *FATAL*-ILLEGAL SWITCH OR FILESPEC 
SHIRLEY.MAC;2/CF 


@e SLP followed by a dash, the type of error message, the error 
message, and the name of the file with which the error is 


associated. For example: 


SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename 


Note that all but two of the SLP error messages are fatal. The 
two exceptions are diagnostic messages, which are described at 
the end of this section. 


SLP -- *FATAL*-COMMAND SYNTAX ERROR 
command line 


Explanation: The command line format did not conform to 
syntax rules. Open files were closed and SLP was 
reinitialized. 
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User Actions Reenter the command line, specifying the 
proper syntax. 


SLP -- *FATAL*-ILLEGAL DEVICE NAME 
command line 


Explanation: The device specified was not a legal device. 
Open files were closed and SLP was reinitialized. 


User Actions Reenter the command line, specifying a legal 
device. 


SLP -- *FATAL*-ILLEGAL DIRECTORY 
command line segment 


Explanation: The directory was not legally specified. Open 
files were closed and SLP was reinitialized. 


User Action: Reenter the command line, specifying a legal 
directory. 


SLP -- *FATAL*-ILLEGAL ERROR/SEVERITY CODE pl p2 p3 


Explanation: This error message indicates an error in the 
SLP program. 


User Actions Reenter the command line. If this does not 
correct the problem, call your DIGITAL Customer Support 
Center. 


SLP -- *FATAL*-ILLEGAL FILE NAME 
command line segment 


Explanation: A file specification was greater than 19 
(decimal) characters in length or contained a wildcard (that 
is, an asterisk in place of a file specification element). 
Open files were closed and SLP was reinitialized. 


User Action: Reenter the command line, specifying a legal 
filename. 

SLP -- *FATAL*-ILLEGAL GET COMMAND LINE ERROR 
Explanation: The system was unable to read a command line. 


This error message indicates an internal system failure or 
an error in the SLP program. 
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User Actions Reenter the command line. If this does not 
correct the problem, call your DIGITAL Customer Support 
Center. 


- *FATAL*-ILLEGAL SWITCH OR FILESPEC 


command line segment 


SLP 


Explanation: The switch was not a legal SLP switch or a 
legal switch was used in an illegal manner, or a file 
specification could not be parsed. 


User Actions Reenter the command line, specifying the legal 
Switch, or correct the file specification. 


- *FATAL*-INDIRECT COMMAND SYNTAX ERROR 


command line 


oLP 


Explanation: The command line format specified for the 
indirect command file did not conform to syntax rules. Open 
files are closed and SLP was reinitialized. 


User Action: Reenter the command line, specifying the 
proper syntax. 


- *FATAL*-INDIRECT FILE DEPTH EXCEEDED 


command line 


oLP 


SLP 


SLP 


Explanation: More than three levels of indirect command 
files were specified in an indirect command file. Open 
files were closed and SLP was reinitialized. 
User Actions Correct the indirect command file and reenter 
the command line. 
-~ *FATAL*-I/O ERROR COMMAND INPUT FILE 

or 


- *FATAL*-I/0Q ERROR COMMAND OUTPUT FILE 


or 


-- *FATAL*-I/0 ERROR CORRECTION INPUT FILE filename 


or 


- *FPATAL*-I/O ERROR LINE LISTING FILE filename 
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or 
OLP -- *FATAL*-I/O ERROR SOURCE OUTPUT FILE filename 
| 
Explanation: One of the following conditions may exist: 
| 


e@ A problem exists on the physical device. 


@® The length of the command line was greater than the 
allowed number of characters. 


@e The file is corrupted or the format is incorrect. 


User Actions Determine which condition caused the message 
and correct that condition. Reenter the command line. 


SLP -- *FATAL*-INDIRECT FILE OPEN FAILURE 
command line 


or 

SLP -- *FATAL*-OPEN FAILURE CORRECTION INPUT FILE filename 
or 

SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename 
or 

SLP -- *FATAL*-OPEN FAILURE SOURCE OUTPUT FILE filename 


Explanation: One of the following conditions may exist: 
e The file is protected against an access. 

e A problem exists with the physical device 

@e The volume is not mounted. 

@® The specified file directory does not exist. 


@® The named file does not exist in the specified 
directory. 


@e The available Executive dynamic memory is insufficient 
for the operation. 


These errors cause open files to be closed and SLP to _ be 
reinitialized. 
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User Actions Determine which condition caused the message 
and correct that condition. Reenter the command line. 


SLP -- *FATAL*-LINE NUMBER ERROR 
command line 


Explanation: The command line printed contained an 
illegally specified numeric line locator. 


User Actions Terminate the SLP edit session and refer to 
the rules for specifying numeric line locators in Section 
11.3.1. Correct the error and reenter the command line. 


SLP -- *FATAL*-PREMATURE EOF CORRECTION INPUT FILE filename 


Explanation: An out-of-range line locator was specified in 
an indirect command file or from the terminal; for example, 
-990 was specified for an 800-line file. | 


User Action: Terminate the current editing session. 
Restart the editing session, and enter the edit command 
line, specifying the correct line number. 


SLP -- *FATAL*-PREMATURE EOF COMMAND INPUT FILE 


Explanation: This is caused by not terminating SLP command 
input with a slash (/) or by inadvertently typing CTRL/Z at 
the terminal, which sends an end-of-file to SLP before the 
slash (/) character is read. SLP prompts (SLP>), indicating 
that a new file specification is expected. 


User Action: Restart the editing session at the point where 
the CTRL/Z was typed. 


SLP -- *DIAG*-ERROR IN COMMAND FILE filespec CHECKSUM 


Explanation: An incorrect value was specified for the 
command file checksum. If you enter the edit command lines 
directly from the terminal, the command file in the error 
message is CMI.CMD. Thus, the error message reads: 


SLP -- *DIAG*-ERROR IN COMMAND FILE CMI.CMD CHECKSUM 
User Action: This is a warning message only. The specified 


output file is still created, although possibly not as 
intended. 
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SLP -- *DIAG*-n LINES TRUNCATED BY AUDIT TRAIL 
command line 


Explanation: Line truncation by the audit trail was 
detected. 


User Actions This is an informational message only. The 
specified output file is still created. (In the listing 
file, a question mark (?) replaces the period (.) in the 
line number of the lines that were truncated. It is 
possible that audit-trail strings from the input file will 
be truncated by the new audit-trail string although text 
Strings will not be truncated.) Determine where the 
truncation(s) occurred. If necessary, modify the command 
file so that it contains commands that do not’ cause 
truncation. 
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The Convert Utility (CVT) provides you with a convenient means of 
converting an integer value into several different radixes. 


To invoke CVT, enter the following command from DCL: 
S RUN SCVT 
You receive the following prompt: 


CVvT> 


Once you receive the CVT prompt, you can enter an integer 
expression. Figure 12-1 illustrates the output of CVT when you 
enter the value 15 (octal). 


S$ RUN SCVT ! Execute the Convert Utility. 
CVT> 15 


se. -134.50% — enone’ $SO0O00D % M "<CR ><NUL> 


| | | | | | 
Decimal Decimal Octal Octal Hex RAD50 ASCII 


Word Bytes Word Bytes Word Word Bytes 


Figure 12-1: Output of the CVT Utility 


CVT displays a row of numbers that represent the value 15 (octal) 
converted into a decimal word, decimal bytes, octal word, octal 
bytes, hexadecimal word, RAD50 word, and ASCII bytes. 


By default, CVT interprets the expression you specify as an octal 
value. However, you can force CVT to interpret the expression as 
decimal, hexadecimal, RAD50, or ASCII. To do this, you use _ the 
punctuation described in Table 12-1. Note that CVT uses the same 
punctuation in its output display to indicate the radix of each 
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value. 


Table 12-1: Punctuation to Specify Radix 


Name Example Description 


Period 13. Forces decimal interpretation. Place 
the period immediately after the 
value you want interpreted as 


decimal. 
Dollar SD | Forces hexadecimal interpretation. 
Sign Place the dollar sign immediately 


before the value you want 
interpreted as hexadecimal. 


rove 
- 


Percent Forces RAD50 interpretation. Place 

Sign the percent sign immediately before 
the value you want interpreted as 
RAD50. You can enter from one to 
three RAD50 characters at a time. 


Apostrophe ux Forces ASCII interpretation of 1 
byte. Place the apostrophe 
immediately before the value you 
want interpreted as an ASCII byte. 
You can enter no more than one 
character after an apostrophe. 


Quotation UX Forces ASCII interpretation of two 

Mark bytes. Place the quotation mark 
immediately before the value you 
want interpreted as two ASCII bytes. 
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The Peripheral Interchange Program (PIP) is a file utility 
program that transfers data files from one standard FILES-11 
device to another. PIP also performs file control functions. 
Some of the functions PIP performs are: 

® Copying files from one device to another 

@e Deleting files 

@ Renaming files 

e Listing file directories 


e Setting the default device and UIC for PIP operations 


@® Unlocking files 


13.1 INVOKING PIP 

You can invoke PIP in two ways: 

1. Invoke the DCL commands that manipulate files; these commands 
in turn invoke PIP. See Section 1.1.1 for a list of 
file-handling commands. 

2. Invoke PIP directly from the DCL command level. 

To invoke PIP directly from the DCL command level, enter’ the 


following command: 


S RUN SPIP 
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You receive a new prompt to indicate that you are in the PIP 
environment: 


PIP> 


Once you are in the PIP environment, PIP waits for your command. 
The following section describes the command format. 


13.2 FORMAT OF PIP COMMANDS 

The simplest format for the PIP command line is: 
outfile=infile 

outfile 
The output file specification. If the output filename, file 
type, and version are either defaulted or *.*;*, the input 
Filename, file type, and version are used for the output 
file (see /NV and /SU subswitches). 
If you explicitly specify any portion of the output file 
Specification (filename, file type, or version), wildcards 
cannot be used in this specification. 
Similarly, for a copy command, if you enter any portion of 
the output specification, you can enter only one file as the 
input file. 

infile 


The input file specification. If the filename, file type, 
and version fields are not specified, then *.*;* is the 


default. 
One switch that you can specify when copying FILES-11 files is 
the Merge switch (/ME). The Merge switch creates a new file from 
two or more existing files. PIP assumes /ME when you explicitly 


specify an output file, two or more input files, and no switches. 
Because the basic copy function and the Merge switch are 
logically related, the Merge switch is described here rather than 
with the other switches. 


The general format of the PIP command line is: 


outfile=infilel[,infile2...,infilen][[/ME][/subswitch] ] 
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outfile 


The output file specification. 


infile 


The input file specification. 


/ME 


The Merge switch. 


/subswitch 


Specifies any of the subswitches that you can enter as part 
of the basic command line or with the Merge switch. (Table 
13-2 describes these subswitches. ) 


subswitches can appear in either the output or input file 
Specification. If you place the subswitch in an input file 
Specification, it applies only to that file. If you place 
the subswitch in the output file specification, it applies 
to the entire list of input specifications. 


13.3 PIP DEFAULTS FOR FILE SPECIFICATION FIELDS 


With the exception of the version number, PIP generally uses’ the 
last value encountered in the command line as the default. That 
is, PIP uses values you enter to set defaults and changes’ the 
default when you change the value. Exceptions to this are noted 
in the descriptions of each switch. 


In the following example, T1.MAC;5 sets the defaults for the 
subsequent file specifications in the command line. Then, T2 is 
specified and overrides Ti as the default filename; however, .MAC 
remains the default file type. Finally, .TSK is specified, which 
overrides .MAC as the default, while T2 remains the default 
filename. 


Note, in this example, that the version number does not default. 
PIP>T1.MAC;5,T2,.TSK/BR 
T1.MAC;5 


T2.MAC;1 
T2.7TSK3 


13-3 


PIP DEFAULTS FOR FILE SPECIFICATION FIELDS 


Table 13-1 summarizes the rules PIP uses to set defaults. 


Table 13-1: PIP Default File Specifications 


Field Default Value 


dev: For the first file specification, the unit on 
which the user’s system disk 1S mounted (SYQ:) or 
the default that you specify with the /DF switch. 


For subsequent file specifications, either you 
explicitly specify a new device or PIP assumes the 
device from the previous specification. 


[ufd] For the first file specification, your current 
User Identification Code (UIC)--the UIC under 
which you log on, the UIC you specify with the SET 
command, or the default you specify with the /DF 
Switch. 


For subsequent file specifications, either you 
explicitly specify a new User File Directory or 
PIP assumes the UFD from the previous | 
specification. Only the asterisk specification 1s 
valid as a wildcard. 


filename No default for the first file specification. For 
subsequent file specifications, the last file name 
that you explicitly specified. Asterisk and 
percent sign specifications are valid as 
wildcards. 


.filetype No default for the first file specification. For 
subsequent file specifications, the last file type 
that you explicitly specified. Asterisk and 
percent sign specifications are valid as 
wildcards. 
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Field Default Value 


;version The default for input files is the most recent 
version number. The default for output files is 
the next higher version number, or version 1 if 
the file does not exist in the output directory. 
An exception is the PIP file delete function, 
which requires that a version number be specified. 


An explicit version number is defined to be of the 
form ;n where n is greater than 0. A version 
number of ;-1 may be used to specify the oldest 
version of a file. A version number of ;0 or ; may 
be specified to signify the most recent version. 
In certain cases, just the asterisk (wildcard) may 
be specified. 


13.4 PIP SWITCHES AND SUBSWITCHES 


PIP provides several file control switches and subswitches. A 
Switch specification consists of a slash (/) followed by a two- 
or three-character switch name. 


The switch specification is optionally followed by a _ subswitch 
name separated from the switch name by a slash. The switch or 
subswitch can have arguments that are separated from the switch 
or subswitch name by a colon (:). 


To allow several commands to be performed consecutively, more 
than one command can be specified in a line. To separate each 
command, the ampersand character (&) is used. 


Most of the PIP switches operate on lists of file specifications. 
The exceptions are /DD, /DF, /ID, and /TD, which are used by 
themselves. 


Table 13-2 lists PIP switches and subswitches and summarizes’ the 
functions performed by them. The subswitches are listed with 
their respective switches. The switches and subswitches are 
described in detail in Section 13.4.1. 
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Table 13-2: PIP Switches and Subswitches 


Switch Subswitch 
/AP 
FO 
/CD 
DE 
LD 
DD 
DF 
EN 
NV 


EOF[(:block:byte] 


BX 


/FI:filenum: seqnum 


FR 


ID 


Function 


Appends file(s) to the end of an 
existing file. 


Specifies the file owner for a file. 


Allows the output file to take the 
creation date of the input file rather 
than the date of transfer. 


Deletes one or more files. 
Lists the deleted files. 


Restricts file searches to files 
created during a specified period of 
time. 


Changes PIP’s default device and/or 
UED. 


Enters a synonym for a file ina 
directory file. 


Forces the version number of a file to 
one greater than the latest version. 


Specifies the end-of-file pointer for 
a file. 


Excludes one file specification from 
the PIP operation. 


Accesses: a Tule by 1ts file 
identification number (file-ID). 


Displays the amount of available space 
on the specified volume, the largest 
contiguous free space on that volume, 
and the number of available file 
headers. 


Identifies the version of PIP being 
used. 
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LI 


ME 


NM 
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Subswitch 
BR 
FU[:n[.]] 
TB 
Bint «| 
CO 

FO 

NV 

SU 

FO 

GR[ :RWED] 
OW[ :RWED] 
SY[:RWED] 


Function 
Lists directory files. 


Lists a directory file in brief format 
(an alternative mode for the /LI 
Switch). 


Lists a directory file in full format 
(an alternative mode for the /LI 
Switch). 


Lists the total number of blocks used 
for a directory, along with the total 
number of blocks allocated and the 

number of files in that directory (an 
alternative mode for the /LI switch). 


Concatenates two or more files into 
one file. 


Allocates a number (n) of contiguous 
blocks. 


Specifies that the output file(s) be 
contiguous. 


Specifies the file ownership for a 
file. 


Forces the version number of a file to 
one greater than the latest version. 


Supersedes (replaces) an existing 
file. 


Suppresses certain PIP error messages. 


Changes the protection status of a 
file. 


Specifies the ownership for a file. 


Sets the read/write/extend/delete 
protection at the group level. 


Sets the read/write/extend/delete 
protection at the owner level. 


Sets the read/write/extend/delete 
protection at the system level. 
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Switch Subswitch Function 
WO[ :RWED ] Sets the read/write/extend/delete 
protection at the world level. 
/PU[:n[.] ] Deletes obsolete version(s) of a file. 
LD Lists the deleted files. 
RE Renames a file. 
RM Removes a file entry from a directory. 
SD Selectively deletes files by prompting 


for your response before deleting. 


SR Allows shared reading of a file that 
has already been opened for writing by 
another user or task. 


TD Restricts file searches to files 
created on the current day. 


TR Truncates files to logical 
end-of-file. 

UF Creates a User File Directory entry on 
the volume to which a file is being 
transferred. 

UN Unlocks a file. 

UP Updates (rewrites) an existing file. 

FO Specifies the owner for a file. 


13.4.1 Switches 


PIP accepts some switches with no file specification. However, 
when you use a switch in a command line, it must follow the file 
or directory specification. It cannot come before the device 


name, the directory, the filename, file type, or version of the 
file on which it is to operate. 


You may specify a switch once for a list of file specifications. 
For example: 
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_filespeci,filespec2,filespec3/DE 


The /DE switch applies to all of the file specifications. PIP 
deletes every specified file from its UFD. 


You specify switch arguments as octal (default), decimal, or 
alphabetic characters, depending on the switch. The sections 
that explain the individual PIP switches discuss these values. 


13.4.2 Subswitches 


You can apply subswitches to one or more file specifications, 
depending on the placement of the subswitch. Subswitches can 
appear in either the output file specification or the input file 
specification. 


If you place the subswitch in the output file specification, the 
subswitch applies to the entire list of input file 
Specifications. For example, the Contiguous Output switch (/CO) 
is applied to both TEST.TSK and SAMP.DAT. (The /CO switch is 
used with the Copy function.) 


PIP>/CO=TEST.TSK;1,SAMP.DAT;1 


PIP copies TEST.TSK;1 and SAMP.DAT;1 such that the copies, 
TEST.TSK;2 and SAMP.DAT;2, are contiguous. 


If you place the subswitch in the input file specification, it 
usually applies only to the file specification that immediately 
precedes it. In the following example, the New Version subswitch 
(/NV) is applied to the file ASDG.MAC. (The /NV subswitch 1s 
being used with the Rename switch, /RE.) 


PIP>*.SMP=PRT2.QRT,ASDG.MAC/NV, KG.MAC/RE 


PIP renames the files PRT2.QRT and KG.MAC, but they maintain 
their associated version numbers. File ASDG.MAC is also renamed, 
but the version number is forced to a number one greater than the 
latest version of file ASDG.SMP (assuming a version of ASDG.SMP 
already exists). 


When you explicitly apply a subswitch to a file specification, 
you implicitly apply the switch with which the subswitch is 
associated. On a command line with more than one file 
specification, the explicit subswitch affects only the file to 
which it is applied. The implicit switch affects all the files 
on the command line. 
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Example 
PIP>FILE1.CMD/GR:R/WO, FILE2.MAC/GR: RW 
This command is equivalent to: 
PIP>FILE1.CMD/GR:R/WO, FILE2.MAC/GR:RW/PR 


The command results in the following file protection: 


a. FILE1 SYSTEM -- Unchanged 
MEMBER -- Unchanged 
GROUP -- Read access 
WORLD == <NO. “access 
b. FILE2 SYSTEM -- Unchanged 
MEMBER -- Unchanged 
GROUP ~- Read/write access 
WORLD -- Unchanged 


13.5 SPECIFYING WILDCARDS 


PIP allows you to specify wildcards in file specifications. The 
wildcard characters are the asterisk (*) and the percent sign (3%) 
characters. You can use both wildcards in place of explicit 
Specifications for filenames and file types. Use only the 
asterisk wildcard in place of file directories and version 


numbers. 


The asterisk can denote zero or more characters in the field you 
specify it in, while the percent sign character denotes a single 
character in ae field. (Correct syntax must be followed, 


however.) 


Wildcards are restricted in some cases. The following sections 
describe and give examples of wildcards in input and output file 
specifications. 


13.5.1 Wildcards in Output File Specifications 
Wildcards in the output file specifications are restricted. For 


the following PIP functions, the output file specification cannot 
have any wildcards: 
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@® cConcatenating files to a specified file 

@ Appending files to an existing file 

® Updating (rewriting) an existing file 

e Listing a directory 

If you use wildcards in the output file specification for any of 
these functions, the meaning of the command line would be 
ambiguous. For example: 


PIPSLIST.*=[USERFILES]/LI 


You have incompletely specified the output file specification. 
PIP returns an error message. 


When you make copies of several files, the output specification 
must be *.*;* or defaulted from the input file specification(s). 


For the Rename (/RE) and Enter (/EN) switches, the output 
Specification may have wildcards (asterisk only) mixed with 
specified fields. For either switch, the equivalent field of the 
input file specification is used. 

For all cases in which wildcards are allowed in the output file 
specification, the wildcard directory form [*] is used to 
indicate that the output directory is to be the same as the input 
directory. 


NOTE 


The percent sign (%) cannot be used in output 
File specifications. 


13.5.2 Wildcards in Input Specifications 


PIP provides the following wildcard features for input file 
specifications: 


@® *.*;* means all versions of all files. 
@® *.DAT;* means all versions of all files of file type .DAT. 


@® *.D*;* means all versions of all files with file types 
beginning with D. 


13-11 


PIP 


SPECIFYING WILDCARDS 


TEST.*;* means all versions of all types of files named TEST. 


T*.*;* means all versions of all types of files with names 
beginning with T. 


TEST.DAT;* means all versions of file TEST.DAT. 
TEST.D%T;* means all versions of files named TEST with 
three-character file types beginning with D and ending with 


Ls 


TSON.*;* means all versions of all file types of all 
three-character filenames beginning with T and ending with N. 


k*.* means the most recent version of all files. 


*,DAT means the most recent version of all files of file type 
-DAT. 


*%.DAT means the most recent version of all files that have 
at least one character in their names and have the file type 
of .DAT. 

TEST.* means the most recent version of all file types for 
files named TEST. 


also provides the following wildcard directory features: 


[*,*] means all group,member number combinations (1 to 37/7 
octal). 


[ni,*] means all member numbers under group ni. 
[*,n2] means all group numbers for member n2. 


[*] means all directories. 


NOTE 


The percent sign (%) character cannot be used in 
the directory. 


13.6 PIP ERROR MESSAGES 


The PIP error messages, their descriptions and suggested user 
actions are as follows: 
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PIP -- ALLOCATION FAILURE - NO CONTIGUOUS SPACE 


Explanations Not enough contiguous space was available on 
the output volume for the file being copied. 


User Action: Delete all files that are no longer required 
on the output volume, then reenter the command line. 


PIP -- ALLOCATION FAILURE ON OUTPUT FILE 
Or 
PIP -- ALLOCATION FAILURE - NO SPACE AVAILABLE 


Explanations: Not enough space was available on the output 
volume for the file being copied. 


User Action: Delete all files that are no longer’ required 
on the output volume, then reenter the command line. 

PIP -- BAD USE OF WILD CARDS/CHARACTERS IN DESTINATION FILE NAME 
Explanation: A wildcard/character was specified for an 
output filename when use of a wildcard/character was 
explicitly disallowed. 

User Action: Reenter the command line with the output file 
explicitly specified. 

PIP -- CANNOT EXCLUDE *.*;* 


Explanation: The /EX switch does not accept all wildcards 
as the input file specification. 


User Action: Determine the files to be excluded and reenter 
the command line. 
PIP -- CANNOT FIND DIRECTORY FILE 


Explanation: The specified directory does not exist on the 
volume. 


User Actions Reenter the command line, specifying the 
correct directory or the correct volume. 
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PIP ~- CANNOT FIND FILE(S) 


Explanations The file(s) specified in the command line 
was(were) not found in the designated directory. 


User Action: Check the file specification and reenter’ the 
command line. 

PIP -- CANNOT RENAME FROM ONE DEVICE TO ANOTHER 
Explanations You attempted to rename a file across devices. 
User Actions Reenter the command line, renaming the file on 
the input volume, then enter another command to transfer the 
file to the intended volume. 

PIP == CANNOT TRUNCATE THIS FLLETYPE 


Explanation: PIP can only truncate files containing 
fixed-length, variable-length, and sequenced records. 


User Action: Check the file specification and reenter’ the 
command line. 


PIP == CLOSE FALLURE ‘ON, INPUT FILE 
or 
PIP =] ChOSE: FATLURE ON: OUTPUT PILE 


Explanation: The input or output file could not be properly 
closed. If the failure is on the output file, the output 
file is then locked to indicate possible corruption. 


User Action: Reenter the command line. If the error 
recurs, run a validity check of the file structure using the 
File Structure Verification Utility (VFY) on the volume in 
question to determine if it is corrupted. 

PIP -- COMMAND SYNTAX ERROR 


Explanation: Command did not conform to syntax rules. 


User Action: Reenter the command line with the correct 
syntax. 
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-- DEVICE NOT MOUNTED/ALLOCATED 


Explanation: The drive had not been allocated, the device 
was not mounted, or another user had mounted the device. 


User Action: Allocate the drive and/or mount the device, 
then reenter the command line. 


-- DIRECTORY WRITE PROTECTED 


Explanation: PIP could not remove an entry from a directory 


because the device 
privilege violation. 


was write-protected or because of a 


User Actions Enable the device for write operations or have 
the owner of the directory change its protection. 


-- ERROR FROM PARSE 


Explanation: The specified directory file does not exist. 


User Actions: Reenter the command line with the correct UIC 


specified. 


-- EXPLICIT OUTPUT FILENAME REQUIRED 


Explanation: Self-explanatory. 


User Action: Reenter 


the command line with the output 


filename explicitly specified. 


-- FAILED TO ATTACH OUTPUT DEVICE 


or 


-- FAILED TO DETACH OUTPUT DEVICE 


Explanation: An attempt to attach/detach a record-oriented 


output device failed. 


This is usually caused by the device 


being off-line or nonresident. 


User Action: Ensure that the device is on-line and reenter 


the command line. 


-- FAILED TO ATTACH TERMINAL 
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Explanation: PIP could not attach a terminal, probably 
because of a privilege violation. 


User Actions: Determine the cause of the failure and correct 
it. Reenter the command line. 

PIP -- FAILED TO CREATE OUTPUT directory 
Explanation: PIP could not create an entry in a directory 
because the device was write-protected or because of a 


privilege violation. 


User Action: Enable the unit for write operations or have 
the owner of the directory change its protection. 


PIP -- FAILED TO DELETE FILE 
or 
PIP -- FAILED TO MARK FILE FOR DELETE 


Explanation: You attempted to delete a protected file. 
User Actions Change the protection of the file if possible, 
and reenter the command line. 

PIP -- FAILED TO ENTER NEW FILE NAME 
Explanation: You specified a file that already exists in 
the directory file, or you did not have the necessary 
privileges to make entries in the specified directory file. 
User Actions Reenter the command line, ensuring that the 
filename and directory are specified correctly. 


PIP -- FAILED TO FIND FILE(S) 


Explanation: The file(s) specified in the command line 
was(were) not found in the designated directory. 


User Action: Check the file specification and reenter’ the 
command line. 
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PIP -- FAILED TO GET TIME PARAMETERS 


Explanation: An internal system failure occurred while PIP 
was trying to obtain the current date and time. 


User Actions Reenter the command line. If the problem 
persists, submit a Software Performance Report (SPR). 


PIP -- FAILED TO OPEN INDEX FILE 


Explanation: PIP was unable to read the index file, 
probably because of a privilege violation. 


User Action: Retry the operation by running PIP under a 
system UIC, or have the system manager change the protection 
on the index file. 


PIP -- FAILED TO OPEN STORAGE BITMAP FILE 


Explanation: PIP could not read the specified volume’s 
storage bitmap, probably because of a privilege violation. 


User Action: Retry the operation by running PIP under a 
system UIC, or have the system manager change the protection 
on the storage bitmap. 


PIP -- FAILED TO READ ATTRIBUTES 


Explanation: The volume you specified was corrupted or you 
did not have the necessary privileges to access the file. 


User Actions Ensure that PIP is running under the correct 
ULC. If the UIC is correct, then run the validity check 
using the File Structure Verification Utility (VFY) against 
the volume in question to determine where and to what extent 
the volume is corrupted. 


PIP -- FAILED TO REMOVE DIRECTORY ENTRY 
Explanation: PIP could not remove an entry from a directory 
because the unit was write-protected or because of a 


privilege violation. 


User Action: Enable the unit for write operations or have 
the owner of the directory change its protection. 
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PIP -- FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST 


Explanations: PIP has removed a file from a directory, 
failed to enter it (using /RE) into another directory, and 
failed to replace the original directory entry. 


User Actions Run the lost check of the File Structure 
Verification Utility (VFY) to recover the filename. 


PIP ~- FAILED TO TRUNCATE FILE 


Explanations The volume you specified is corrupted or _ you 
did not have the necessary privileges (write, extend) to 
truncate this file. 


User Actions Ensure that PIP is running under the correct 
UIC. If the UIC is correct, then run the validity check of 
the File Structure Verification Utility (VFY) against the 
volume in question to determine where and to what extent the 
volume is corrupted. 


PIP -- FAILED TO WRITE ATTRIBUTES 


Explanation: The volume you specified is corrupted or _ you 
did not have the necessary privileges to write the file 
attributes. 


User Actions Ensure that PIP is running under the correct 
ULC. If the UIC is correct, then run the validity check of 
the File Structure Verification Utility (VFY) against the 
volume in question to determine where and to what extent the 
volume is corrupted. 


PIP == FILE. 15 bOst 


Explanations: PIP has removed a file from its directory, 
failed to delete it, and failed to restore the directory 


entry. 


User Action: Run the lost check of the File Structure 
Verification Utility (VFY) to recover the filename. 
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PIP -- FILE NOT LOCKED 


Explanations The /UN switch was entered for a file that was 
not locked. 


User Action: Reenter the command line, specifying the 
correct file. 
PIP -- GET COMMAND LINE - BAD @ FILE NAME 


Explanations An illegal indirect command filename was 
specified. 


User Actions Reenter the command line, specifying the 
correct name for the indirect command file. 
PIP - GET COMMAND LINE - FAILED TO OPEN @ FILE 


Explanations PIP could not find the specified indirect 
command file. 


User Actions Check the specification for the indirect 
command file and reenter the command line. 
PIP -- GET COMMAND LINE - I/O ERROR 


Explanation: An I/O error occurred during an attempt to 
read a command line. 


User Actions Check the command to ensure that you entered 
it correctly, then reenter the command line. If the error 
persists, submit a Software Performance Report (SPR). 


PIP -- GET COMMAND LINE - MAX @ FILE DEPTH EXCEEDED 


Explanation: The maximum level of nesting for indirect 
command files (4) was exceeded. 


User Action: Reduce the level of nesting. 


PIP -- ILLEGAL COMMAND 
Explanation: The command was not recognized by PIP. 
User Action: Reenter the command line with the PIP command 


correctly specified. 
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PIP -- ILLEGAL EOF VALUE 


Explanations You specified an illegal block and/or byte 
value in the command line. 


User Action: Reenter the command line with the correct 
values. 

PIP -- ILLEGAL RESPONSE - TRY AGAIN 
Explanation: Self-explanatory. 
User Action: Check which response you want and enter it 
when PIP prompts you. 

PIP -- ILLEGAL SWITCH 


Explanations The specified switch was not a legal PIP 
Switch. 


User Action: Reenter the command line with the correct 
Switch specification. 

PIP -- ILLEGAL "*" COPY TO SAME DEVICE AND DIRECTORY 
Explanation: You attempted to copy all versions of ae file 
into the same directory that is being scanned for input 
files. This would result in an infinite number of versions 
of the same file, so is not allowed. 
User Actions: Reenter the command line, renaming the files 
or copying them into a different directory. 

PIP -- ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION 
Explanation: The use of either a wildcard version number or 
a latest version number in the attempted operation would 


result in inconsistent or unpredictable output. 


User Action: Reenter the command tIline with different 
options or with an explicit or default version number. 
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PIP -- INPUT FILES HAVE CONFLICTING ATTRIBUTES 


Explanation: The input files specified in a Merge, Update, 
or Supersede command had conflicting attributes or the 
attributes of the input file(s) specified in an Append 
command conflicted with those of the output file. 


User Action: The message is a warning only. The specified 
action was completed despite the conflict. With a Merge, 
Update, or Supersede command, the attributes of the output 
File will be those of the first input file. With an Append 
command, the attributes of the output file are unchanged. 
The resulting file should, however, be suspect because its 
attributes may not correctly represent all the records in 


the file. 
PIP -- I/O ERROR ON INPUT FILE 
or 
PIP -- I/O ERROR ON OUTPUT FILE 


Explanation: One of the following conditions may exist: 
@e The device is not on-line 

@e The device is not mounted 

e The hardware has failed 

@e The volume is full (output only) 

e The input file is corrupted 


Note that these are the most common conditions. Conditions 
other than those listed may have caused the message. 


User Actions Determine which condition caused the message 
and correct that condition. Reenter the command line. 
PIP -- NOT A DIRECTORY DEVICE 


Explanation: A directory-oriented command was issued to a 
device that does not have directories (such as a printer). 


User Action: Reenter the command line without specifying a 
directory. 
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PIP -- NOT ENOUGH BUFFER SPACE AVAILABLE 


Explanation: PIP did not have enough I/O buffer space to 
perform the requested command. 


User Action: You cannot use PIP to perform the requested 
operation. Submit a Software Performance Report to your 
local DIGITAL representative. 


PIP -- NO SUCH FILE(S) 


Explanations: The file(s) specified in the command was(were) 
not found in the designated directory. 


User Actions Check the file specification and reenter’ the 
command line. 


PIP -- ONLY [*] IS LEGAL AS DESTINATION UIC 


Explanation: A directory other than [*] was specified as 
the output file directory for a copy operation. 


User Actions Reenter the command line with [*] specified as 
the output directory. 


PIP -- OPEN FAILURE ON INPOT FILE 


or 
PIP -- OPEN FAILURE ON OUTPUT FILE 
Explanation: The specified file could not be opened. One 


of the following conditions may exist: 


e The file is protected against access. 

e A problem on the physical device (for example, device 
down). 

@e The volume is not mounted. 

e The specified file directory does not exist. 

e The named file does not exist in the specified 
directory. 

Note that these are the most common conditions. Conditions 
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other than those listed may have caused the message. 
User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 

PIP -- OUTPUT FILE ALREADY EXISTS -- NOT SUPERSEDED 


Explanation: An output file of the same name, type, and 
version as the file specified already exists. 


User Action: Retry the copy with /NV to assign a new 
version number or use /SU to supersede the output file. 
PIP -- TOO MANY COMMAND SWITCHES - AMBIGUOUS 


Explanations: Too many switches were specified or the 
Switches conflict. 


User Action: Reenter the command line, specifying the 
correct set of switches. 
PIP -- VERSION MUST BE EXPLICIT OR "*" 


Explanation: The version number of the specified file must 
be expressed explicitly or as a wildcard (*). 


User Actions: Reenter the command line with the version 
number correctly expressed. 


13.7 PIP ERROR CODES 
Table 13-3 identifies error codes PIP issues when it cannot 


access the message file. The descriptions and suggested user 
actions are identical to those described in Section 13.6. 


Table 13-3: PIP Error Codes and Messages 


Code Message 
1 Command syntax error 
2 Invalid switch 
3 Too many command switches--ambiguous 
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Only [*,*] is legal as destination UIC 
Invalid command 

Invalid "*" copy to same device and directory 
Bad use of wildcards/characters in destination filename 
Explicit output filename required 

Allocation failure--no contiguous space 
Allocation failure--no space available 
Allocation failure on output file 

I/O error on input file 

I/O error on output file 

Invalid use of wildcard version or latest version 
Failed to create output directory 

Input files have conflicting attributes 

Open failure on input file 

Open failure on output file 

Close failure on input file 

Close failure on output file 

Failed to detach output device 

Device not mounted/allocated 

Output file already exists--not superseded 
Failed to mark file for delete 

File is lost 

Version must be explicit or "*" 

Error from parse 

Failed to delete file 

Failed to attach terminal 

Invalid response--try again 

Cannot exclude *.*;* 

Cannot find directory file 

Failed to attach output device 

Failed to get time parameters 

Not a directory device 

Failed to write attributes 

Failed to read attributes 

File not locked 

Failed to enter new filename 

Failed to restore original directory entry--file lost 
Cannot rename from one device to another 
Failed to spool file for printing 
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Cannot 


PIP ERROR CODES 


spool by file ID 

to open storage bitmap file 
to open index file 

to find file(s) 

find file(s) 


No such file(s) 


Failed 


to remove directory entry 


Directory write protected 
Not enough buffer space available 


Failed 
Cannot 


to truncate file 
truncate this filetype 


Invalid EOF value 
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OBJECT MODULE PATCH UTILITY (PAT) 


The Object Module Patch Utility (PAT) allows you to update, or 
patch, code ina relocatable binary object module. 


Input to PAT is two files, an input file and a correction file. 
The input file consists of one or more concatenated object 
modules. You can correct only one of these object modules with a 
Single execution of PAT. The correction file consists of object 
code that, when linked by the Task Builder, either overlays or is 
appended to the input object module. 


Unlike the Task Builder and ZAP patching options, PAT allows you 
to increase the size of the object module because the changes are 
applied before the module is linked by the Task Builder. 


PAT uses the correction file, which contains corrections and/or 
additional instructions, to update the object module. Correction 
input is prepared in source form and then assembled by the 
MACRO-11 assembler. 


Output from PAT is the updated input file. 


Using PAT to update a file involves several steps. First, you 
create the correction file using a text editor. Once created, 
the correction file must be assembled to produce an object 
module. The correction file and the input file (both in object 
module format) are then submitted to PAT for processing. 


Finally, the updated input object module is submitted to the Task 
Builder to resolve global symbols and to create an executable 
task. Figure 14-1 shows the processing steps involved in 
generating an updated task file using PAT. 
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14.1 INVOKING PAT 
To invoke PAT, enter the following command: 
S RUN SPAT 
PAT can be used interactively or by means of indirect command 


files. If you use indirect command files, PAT allows a maximum 
nesting level of 2. 


14.2 PAT COMMAND LINE FORMAT 

Specify the PAT command line in the following format: 
[outfile]J=infile[/CS[:number]],correctfile[/CS: [number] ] 

outfile 


The file specification for the output file. If you do not 
specify an output file, PAT does not generate one. 


infile 


The file specification for the input file. This file can 
contain one or more concatenated object modules. 


correctfile 
The file specification for the correction file. This file 
contains the updates to be applied to one module in the 
input file. 


/CS[snumber ] 


Specifies the Checksum switch. This switch directs PAT to 
calculate the checksum for all the binary data that 
constitutes the module. PAT displays this checksum in 
octal. (Refer to Section 14.3.4 for information on how to 
use /CS.) 


You can optionally specify an octal number with /CS. Then, 
after PAT calculates the checksum value, it compares that 
value with the number you specified. If the values are not 
the same, PAT informs you with an error message. You must 
then rerun PAT, specifying the correct checksum. 
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TEXT 1. 
EDITOR 


CORRECT SRC 


ae 


CORRECT.OBJ 


MYFILE OBJ 


MYFILE.OBJ 


TASK 
BUILDER 


Figure 14-1: 


Using PAT 


4. 


CORRECT.SRC 


oF 


CORRECT OBJ 


ag 


MYFILE.OBJ 


met) 


Generate a correction file using 
the Text Editor. 


Execute the assembler (or compiler) 
to generate an object module 
version of the file. 


Execute PAT using as input the 
correction file and the module to 
be updated. 


MYFILE TSK 
Execute the Task Builder to 
resolve new addresses and ee 
generate an executable task 
ZK-199-81 


14.3 HOW PAT APPLIES UPDATES 


This section describes the PAT input and correction files, 
create 


information on how to 


gives 


the correction file, and gives 


examples of how PAT applies the corrections to a module. 
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14.3.1 The Input File 


The input file is the file to be updated; it is the base for the 
output file. The input file must be in object module format. 
When you execute PAT, the correction file is applied to one of 
the object modules in the file. PAT assumes a file type of .OBJ 
for the input file. If you use a file type other than .OBJ, you 
must specify it explicitly in the command line. 


14.3.2 The Correction File 


The correction file contains the patches to be applied to _ the 
input file. PAT assumes a file type of .OBJ for the correction 
file. If you use a file type other than .OBJ, you must specify 
it explicitly in the command line. 


As shown in Figure 14-1, the first step in using PAT to update an 
object file is to generate the correction file. Use any text 
editor to create this source file, which is usually in the 
following format: 


.-TITLE inputname 
. IDENT updatenum 
inputline 
inputline 


inputname 


The name of the module to be corrected by the PAT update. 
You must specify the module that you are updating for 
inputname. 


updatenum 


Any value acceptable to the MACRO-11 .IDENT assembler 
directive. Generally, this value reflects the updated 
version of the file to be processed by PAT. 


NOTE 
The .IDENT assembler directive is a required part 
of the correction file. Failure to include an 
. IDENT directive in the file produces’ unusable 
output. 
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inputline 


Lines of input to be used to correct and update the input 
file. 


Once you have created the source version of the correction file, 
you assemble it to produce an object module that can be processed 
by PAT. 


During PAT execution, new global symbols defined in the 
correction file are added to the module’s symbol table. A symbol 
definition that is already being used in the input file can be 
Superseded by the definition in the correction file. Fora 
symbol definition to be superseded, both definitions must be 
either relocatable or absolute. 


A duplicate program section supersedes the previous program 
section, provided: 


@ Both have the same relocatability attribute (ABS or REL) 
@e Both are defined with the same directive (.PSECT or .CSECT) 


If PAT encounters duplicate program section names, the length 
attribute for the program section is set to the length of the 
longer program section and a new program section is appended to 
the module. 


If you specify a transfer address, it supersedes the transfer 
address of the module being patched. 


14.3.3 How PAT and the Task Builder Update Object Modules 


The examples in the following sections show an input file and a 
correction file (both in object module format) to be processed by 
PAT and the Task Builder, along with a source-like representation 
of how the output file looks once PAT and the Task Builder 
complete processing. Two techniques are described: one for 
overlaying lines in a module, and the other for adding a 
subroutine to a module. 


14.3.3.1 Overlaying Lines in a Module - The following 
example illustrates a technique using a patch file to overlay 
lines in a module. First, PAT appends the correction file to the 
input file. Then, the Task Builder generates a task image from 
the patched object modules. 
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The input file for this example is: 


-TITLE ABC 

~-IDENT /01/ 
ABC:: 

MOV A,C 

CALL XYZ 

RETURN 

» END 


To add the instruction ADD A,B after the CALL instruction, you 
can use the following patch in the correction file: 


LITLE ABC 

+L DENT £01. 017 
-=.+12 

ADD A,B 

RETURN 

. END 


You use the MACRO-11 assembler to assemble the correction file. 
After assembly, PAT processes the resulting object module and the 
input object module. The result of PAT processing appears as 
follows: 


.TITLE ABC 
.IDENT /01.01/ 


ABC:: 

MOV A,C 
CALL XYZ 
RETURN 

=ABC 

=.+12 
ADD A,B 
RETURN 
- END 


You then use the Task Builder to produce the patched object 
module as a task image. This task image looks the same as the 
source code would have looked if it had originally been written 
as follows: 


.TITLE ABC 
.IDENT /01.01/ 


ABC:: 
MOV A,C 
CALL XYZ 
ADD A,B 
RETURN 
- END 
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PAT uses the .=.+12 in the program counter field to determine 
where to begin overlaying instructions in the program. It 
overlays the RETURN instruction with the patch code: 


ADD A,B 
RETURN 


14.3.3.2 Adding a Subroutine to a Module - The second 
example illustrates a technique for adding a subroutine to an 
object module. A patch often requires that more than a few lines 
be added to correct the file. A convenient technique for adding 
new code is to append it to the end of the module as a 
subroutine. That way, you insert a CALL instruction at an 
appropriate location in the subroutine. The CALL instruction 
directs the program to branch to the new code, execute that code, 
and then return to in-line processing. 


The input file for this example is: 


-TITLE ABC 
-IDENT /01/ 


ABC: : 
MOV A,B 
CALL XYZ 
MOV C,RO 
RETURN 
- END 


The correction file for this example is: 


-TITLE ABC 
IDENT 701.017 


CALL PATCH 

NOP 

-PSECT PATCH 
PATCH: 

MOV A,B 

MOV DZ RO 

ASL RO 

RETURN 

» END 


PAT merges the correction file with the input file, as in _ the 
first example. The Task Builder then processes the files and 
produces a task image that looks the same as the source file 
would have looked if it had originally been written as follows: 
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-LTITLE ABC 
~-IDENT /01.01/ 


ABC:: 
CALL PATCH 
NOP 
CALL XYZ 
MOV CyRO 
RETURN 
-PSECT PATCH 
PATCH: 
MOV A,B 
MOV D,RO 
ASL RO 
RETURN 
- END 


In this example, the CALL PATCH and NOP instructions overlay the 
3-word MOV A,B instruction. (The NOP is included because this is 
a case where a 2-word instruction replaces a 3-word instruction 
and NOP iS required to maintain alignment.) The Task Builder 
allocates additional storage for .PSECT PATCH, writes the 
specified code into this program section, and binds the CALL 
instruction to the first address in this section. The MOV A,B 
instruction, replaced by the CALL PATCH instruction, is the first 
instruction executed by the PATCH subroutine. 


14.3.4 Determining and Validating the Contents of a File 


You use the Checksum switch (/CS) to determine or validate the 
contents of a module. The switch directs PAT to calculate the 
checksum (in octal) for all the binary data that constitutes the 
module and to then inform you of the checksum by means of a 
diagnostic message. 


To determine the checksum of a file, enter the PAT command line 
with the /CS switch applied to that file’s specification. For 
example: 


=MYFILE/CS,CORRECT.POB 


The command directs PAT to calculate the checksum for the input 
file, MYFILE.PAT then responds with the message: 


INPUT MODULE CHECKSUM IS checksum 
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PAT generates a similar message when you request the checksum for 
the correction file. For example: 
=MYFILE, CORRECT.POB/CS 


After calculating the checksum for the correction file, PAT 
responds with the message: 


CORRECTION INPUT FILE CHECKSUM IS checksum 
If you specify /CS:number to validate the size of a file, PAT 
calculates the checksum for the file and then compares that 
Checksum with the value you specified as number. If the two 
values do not match, PAT displays the following message to report 
the checksum error: 

ERROR IN FILE filename CHECKSUM 
For example, you might specify: 


=MYFILE, CORRECT. POB/CS: 432163 


When PAT calculates the checksum for the correction file, the 
number is different. PAT then displays the message: 


ERROR IN FILE CORRECT.POB CHECKSUM 


Checksum processing always results in an octal, nonzero value. 


14.4 PAT MESSAGES 

PAT generates messages that state checksum values and messages 
that describe error conditions. For checksum values and nonfatal 
error messages, PAT prefixes the messages with: 


PAT -- *DIAG*-error message 


For messages that describe fatal errors (errors that caused PAT 
to terminate), PAT uses the prefix: 


PAT -- *FATAL*-error message 


The following messages are grouped according to message type, as 
follows: 


@® Information messages 
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@e Command line errors 

@e File specification errors 

® Input/foutput errors 

@e File content or format errors 
@ Internal software error 


@e Storage allocation error 


14.4.1. Information Messages 
The following messages describe results of checksum processing. 
CORRECTION INPUT FILE CHECKSUM IS checksum 
Explanations When you specify /CS in the correction file 
specification, PAT informs you of the file’s checksum value. 


The value is given in octal. 


User Actions No response necesSary. 


INPUT MODULE CHECKSUM IS checksum 
Explanations: When you specify /CS in the input file 
Specification, PAT informs you of the file’s checksum value. 
The value is given in octal. 


User Actions No response necessary. 


14.4.2 Command Line Errors 

The following error messages Beene from failure to adhere to the 
command line syntax rules. 

COMMAND LINE ERROR command line 


Explanations The system standard command line processor 
(.GCML) detected an error in the command line. 
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User Actions Reenter the command line using the correct 
information. 

COMMAND SYNTAX ERROR command line 
Explanation: The command line contained a syntax error. 
User Action: Reenter the command line using the correct 
syntax. 

ILLEGAL INDIRECT FILE SPECIFICATION command line 


Explanation: You specified an indirect command file that 
contains one of the following errors: 


@® A syntax error 
@e A specification for a nonexistent indirect command file 
User Actions Check for file specification syntax errors or 
ensure that the specified file is contained in the specified 
User File Directory. Reenter the command line. 

MAXIMUM INDIRECT FILE DEPTH EXCEEDED command line 
Explanation: In the command line, you specified an indirect 
command file that exceeds the maximum nesting level of 2 


that 1s permitted by PAT. 


User Actions: Reorder your files so that they do not’ exceed 
PAT’s nesting limit. 


14.4.3 File Specification Errors 


The following error messages are caused by errors in the 
specification of input or output files or related file switches. 


CORRECTION INPUT FILE MISSING command line 


Explanation: The mandatory correctiron file was not 
specified. 
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User Action: Reenter the command line specifying the 
correction file. 


ILLEGAL DEVICE/VOLUME SPECIFIED device name 


Explanations The device or _ volume name specification 
contained a syntax error. 


User Actions Check the rules for specifying devices and 


volumes, then reenter the command line using the correct 
syntax for the device or volume specification. 


ILLEGAL DIRECTORY SPECIFICATION directory name 


Explanations The directory specification contained a syntax 
error. 


User Actions Check the rules for specifying a directory and 
reenter the command line using the correct syntax for the 
directory specification. 


ILLEGAL FILE SPECIFICATION filename 


Explanation: The file specification contained a syntax 
error. 


User Action: Reenter the command line using the correct 
Syntax for the file specification. 


ILLEGAL SWITCH SPECIFIED filename 


Explanations An unrecognized switch or switch value was 
specified with the file. 


User Actions Check the rules for specifying the switch and 
reenter the command line using the correct switch or switch 


value. 
INVALID FILE SPECIFIED filename 


Explanation: You specified a file that contains one of the 
following errors: 


@e@ Nonexistent device 
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@e Nonexistent directory - The directory in the filename 
specification does not exist on the specified device (or 
on the default device if no device was specified). 

User Action: Reenter the command line specifying the 
correct device or directory. 


MULTIPLE OUTPUT FILES SPECIFIED command line 


Explanation: PAT accepts only one output file 
specification. 


User Action: Reenter the command line specifying only one 
output file. 
REQUIRED INPUT FILE MISSING command line 


Explanation: The mandatory input file was not specified in 
the command line. 


User Actions Reenter the command line specifying an input 
tale. 

TOO MANY INPUT FILES SPECIFIED command line 
Explanation: Too many input files were specified in the 
command line. PAT accepts only the input and correction 
file specifications. 
User Action: Reenter the command line specifying the 
correct files. 


UNABLE TO FIND FILE filename 


Explanation: PAT could not locate the specified input or 
correction file. 


User Action: Check the directory to ensure that the file 


exists. Reenter the command line specifying the correct 
filename. 


14.4.4 Input/Output Errors 


The following error messages are caused by faults detected while 
PAT was performing I/0 to the specified file. 
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ERROR DURING CLOSE: FILE: filename 


Explanation: This error is most likely to occur while PAT 
is attempting to write the remaining data into the output 
file before deaccessing it. The most likely causes of this 
error are the following conditions: 


e The device is full 

e The device is write-locked 

@e A hardware error occurred 

User Actions Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; if the device is write-locked, 


write-enable it; if the problem is a hardware error, contact 
your DIGITAL Field Service representative. 


ERROR POSITIONING FILE filename 


Explanations PAT attempted to position the file beyond 
end-of-file. 


User Action: Submit a Software Performance Report along 
with the related console dialog and any other pertinent 
information. 


I/O ERROR ON INPUT FILE filename 
Explanation: An error was detected while PAT was attempting 
to read the specified input file. The principal cause of 


this error iS a device hardware error. 


User Actions Reenter the command. 


I/O ERROR ON OUTPUT FILE filename 
Explanation: An error occurred while PAT attempted to write 
into the named output file. The most likely causes of this 
error are the following conditions: 


e The device is full 
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e The device is write-locked 
@e A device hardware error occurred 


User Action: Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; if the device is write-locked, 
write-enable it; if the problem is a hardware error, contact 
your DIGITAL Field Service representative. 


14.4.5 Errors in File Contents or Format 


The following errors represent inconsistencies detected by PAT in 
the format or contents of the input or correction files. 


ERROR IN FILE filename CHECKSUM 


FILE 


Explanation: The checksum that PAT calculated for the named 
file does not match the one that you specified with 
/CS:number. 


User Actions: Ensure that you specified the correct 
checksum. If the checksum is correct, then you specified an 
invalid version of the file. Rerun PAT specifying the 
correct version of the file. 

filename HAS ILLEGAL FORMAT 

Explanation: The format of the named file is not compatible 
with the object files produced by the standard DIGITAL 
language processors or accepted by the Task Builder. The 
principal causes are: 

e® Truncated input file 


@® Input file that consists of text 


User Actions: Ensure that the file is in the correct format 
and resubmit it for PAT processing. 
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INCOMPATIBLE REFERENCE TO GLOBAL SYMBOL symbol name 
Explanation: The correction file contains a global symbol 
whose attributes do not match one or more of the following 
input file symbol attributes: 

@e Definition or reference 

@ Relocatable or absolute 

User Actions Update the correction file by modifying the 
symbol attributes. Reassemble the file and resubmit it for 
PAT processing. 

INCOMPATIBLE REFERENCE TO PROGRAM SECTION section name 
Explanation: The correction file contains a section name 
whose attributes do not match one or both of the following 
input file section attributes: 

@ Relocatable or absolute 

@e Defined with the same directive (.PSECT or .CSECT) 

User Actions Update the correction file by modifying the 
section attribute or changing the section type. Reassemble 
the file and resubmit it to PAT for processing. 

UNABLE TO LOCATE MODULE module name 
Explanation: PAT could not find the module name that was. 
Specified in the correction file in the file of concatenated 


input modules. 


User Action: Update the input file specification to include 
the missing module. Reenter the command line. 


14.4.6 Internal Software Error 
This error reflects internal software error conditions. 
ILLEGAL ERROR-SEVERITY CODE error data 


Explanations An error message call, containing an illegal 
parameter, has been generated. 
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User Action: If these messages persist, submit a Software 
Performance Report along with related console dialog and any 
other pertinent information. 


14.4.7 Storage Allocation Error 


The following error message indicates that not enough task memory 
was available for storing global symbol and program section data. 


NO DYNAMIC STORAGE AVAILABLE storage-listhead 


Explanations Not enough contiguous task memory was 
available to satisfy a request for the allocation of 
storage. 


PAT displays the contents of the 2-word dynamic storage 
listhead in octal. 


User Action: You cannot use PAT to correct the input file. 


UNABLE TO OPEN FILE filename 


Explanation: There is insufficient work space in the 
internal File Storage Region (FSR) of the PAT Utility. 


User Action: You cannot use PAT to correct the input file. 
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FILE STRUCTURE VERIFICATION UTILITY (VFY) 


The File Structure Verification. Utility (VFY) for FILES-11 
volumes provides the ability to: 


@e Check the readability and validity of a file-structured 
volume (default function). 


® Print the number of available blocks on a file-structured 
volume (/FR). 


@e Search for files in the index file that are not in any 
directory; that is, files that are "lost" in the sense that 
they cannot be accessed by filename (/LO). 

® Validate directories against the files they list (/DV). 


e® List all files in the index file, showing the file ID, 
filename, and owner (/LI). 


@e Perform a read check on every allocated block on ae file- 
structured volume (/RC). 


The volume to be verified must be mounted as a FILES-11 device. 
There should be no other activity on the volume while VFY is 
executing. In particular, activities that create new files, 


extend existing files, or delete files should not be attempted 
while VFY is executing a function. 


15.1 INVOKING VFY 
To invoke VFY type: 


S RUN SVFY 
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VFY will prompt: 


VEY> 


15.2 VFY COMMAND FORMAT 

The command line for VFY uses the format: 
VFY>listfile,scratchdev=indev/switch 

The parameters of this command format are: 

Output Parameters 

listfile 
Specifies the output listing file in the following format: 

dev: [ufd]filename.filetype;ver 

If you do not specify a device, the default for the output 
listing device is the issuing terminal (TI:). The [ufd] is 
the UIC under which VFY is currently running. You must, 
however, specify the filename and file type of the output 


file. The default version number will be the latest version 
plus one. | 


scratchdev 


Specifies the device on which the scratch file produced by 
VFY is to be written. This parameter is in the following 
format: 


dev: 


The scratch file is used by VFY during the verification scan 


and during the lost file scan. It 1s created but not 
entered ina directory. Therefore, it 1S transparent to 
you. The scratch file is automatically deleted when VFY is 
terminated. If you do not specify a scratch device the 


default device is SYQ:. 


If the user’s default system disk is faulty or full, use 
this parameter to direct the scratch file to another device. 
The scratch file should always be assigned to a volume other 
than the indev volume. The scratch file is not used with 
the /FR and /LI switches. 


Input Parameters 
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indev 


Specifies the volume to be verified in the format dev:. Tf 
you do not specify the volume, the default is SyY0:. 


/switch 


Specifies the function to be performed by VFY. 


15.3 VFY MODE OF OPERATION 


VFY normally operates in read-only mode, where the scratch file, 
if required, iS on another device. 


If the /LO switch is specified and lost files are found, VFY 


requires write access to [1,3], which is the directory containing 
lost files. 


15.4 VEY VALIDITY CHECK 
VFY checks the readability and validity of the volume mounted on 
the specified device. This function is the default function and 
entails reading all the file headers in the index file and 
ensuring that all the disk blocks referenced in the map area of 
each file header are allocated to that file in the volume bitmap. 
The volume may be write-protected if it is not the system volume, 
or if the required scratch file is directed to another file- 
structured volume. 
A validity check is specified in the following format: 

listfile,scratchdev=indev<RET> 

or 
indev<RET> 


Example 


S RUN SVFY 
VFY>DRO: 


CONSISTENCY CHECK OF INDEX AND BITMAP ON DROQ: 
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INDEX INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680 
BITMAP INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680 


15.5 VFY SWITCHES 
VFY functions are specified with switches appended to the VFY 


command line. The switches and their functions are summarized in 
Table 15-1. 


Table 15-1: VFY Switches and Functions 


Switch Format Description 


Directory Validation /DV Validates directories against 
the files they list. 


Free /ER Prints out the available space 
on a volume. 


Identify /ID RaGentifies. the VEY version. 
This switch may be specified on 
a command line by itself at any 


time. 

List /LI Lists the index file by file 
bag Be 

Lost /LO Scans the file structure 


looking for files which are not 
in any directory. 


Read Check /RC Checks the volume to see if 
every block of every file can 
be read. 


15.5.1. Directory Validation Switch (/DV) 


The Directory Validation Switch (/DV) examines each directory on 
the volume. (VFY considers any file on the volume with the file 
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type .DIR and a fixed record length of 16 bytes to be a 
directory.) It then reports any errors found that could be 
attributed to a corrupt directory or a nonexistent file listed in 
the directory. For example: 


S RUN SVFY 

VFY>DX: /DV 

THE FOLLOWING DIRECTORY ENTRIES WERE INVALID 

[301,333] FILE ID 13,2,0 DELETED.FIL;1 - FILE NOT FOUND 

[301,333] FILE ID 12345,3,0 CORRUPTED.FID;1 - FILE NOT FOUND 

(301,333] FILE ID 14,2,0 GARBAGE.VER;123456 - INVALID VERSION NUMBER 

[301,333] FILE ID 15,1,444 RELVOLNEZ.ERO;1 - RESERVED FIELD WAS NON-ZERO 
4. INVALID DIRECTORY ENTRIES WERE FOUND 

Directory entries may be invalid due to the following conditions: 


FILE NOT FOUND 
The file was either deleted without the corresponding 
directory entry being removed or the file ID field in the 
directory entry was corrupted. If the file does exist, it 
cannot be accessed with this directory entry. 
Remove the directory entry using the PIP /RM command. 


INVALID VERSION NUMBER 


The directory entry was corrupted. If the file does exist, 
it cannot be accessed with this directory entry. 


Remove version zero of the file with the PIP /RM command. 
RESERVED FIELD WAS NON-ZERO 

The third word of the file ID field in a directory entry 1s 

a reserved field and should always be zero. Remove the 


directory entry with PIP /RM and then reenter it with the 
PIP /EN command. 


15.5.2 Free Switch (/FR) 


The Free switch (/FR) displays the available space on a specified 
volume with the following message: 


dev: HAS nnnn. BLOCKS FREE, nnnn. BLOCKS USED OUT OF nnnn. 
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15.5.3 List Switch (/LI) 


The List switch (/LI) lists the index file. 


The output for each file specifies the file number, file sequence 


number, filename, and owner UIC, as shown in the following 
example: 
VFY>DK: /LI 
LISTING OF INDEX ON DKO: 
FILE ID 000001,000001 INDEXF.SYS;1 OWNER [1,1] 
FILE ID 000002,000002 BITMAP.SYS;1 OWNER [1,1] 
FILE ID 000003,000003 BADBLK.SYS;1 OWNER [1,1] 
FILE ID 000004,000004 OQ00000.DIR;1 OWNER [1,1] 
FILE ID 000005,000005 CORIMG.SYS;1 OWNER [1,1] 
FILE ID 000006,000006 001001.DIR;1 OWNER [1,1] 
FILE ID 000007,000007 001002.DIR;1 OWNER [1,2] 
FILE ID 000010,000010 EXEMC.MLB;1 OWNER [1,1] 
FILE ID 000011,000011 RSXMAC.SML;1 OWNER [1,1] 
FILE ID 000012,000012 NODES.TBL;1 OWNER [1,1] 
FILE ID 000013 ,000036 QOLOSYM:MSG;311 OWNER {1.2} 
FILE ID 000014,000037 F4PCOM.MSG;1 OWNER [1,2] 


15.5.4 Lost Switch (/LO) 


The Lost switch (/LO) scans the file structure looking for files 
that are not in any directory and cannot be referenced by 
filename. (VFY considers any file the volume with the 
filetype .DIR and a fixed record length of 16 bytes to be a 
directory.) A list of the files 1S produced, and if the "lost 


file 


directory" 


[1,3] 


entered in that directory. 


directory 


[1,3]. 


FAILED TO OPEN DIRECTORY FILE 


ERROR CODE -16. 
AS A RESULT, NO FILES WILL BE ENTERED IN 


file 


operation, 
The following error message will appear: 


the 


= DIRECTORY 


15.5.5 Read Check Switch (/RC) 


files 


exists on that volume, 
Lt: an. 2/0O-error occurs, 
will not be entered into 


E3017 3334 


the files will be 


however, ona 


[1,3] 


of 


The Read Check switch (/RC) checks to ensure that every block 
every file on a Specified volume can be read. 
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The optional parameter [:n] is the blocking factor that indicates 
the number of file blocks to be read at a time. The default 
value is the maximum number of blocks available in VFY’s buffer 
area. The buffer area available may be increased by installing 
VFY ina larger partition. Four blocks are available when VFY is 
installed in an 8K partition, and four blocks are added for each 
1K increment. 


For the fastest read check, the maximum block factor should be 
used. Whenever an error is encountered, each block of the 
portion in error is reread to determine which data _ block(s) 
cannot be read. 


When an error is detected, a file identification line is 
displayed in the following format: 


FILE ID nn,nn filename.typ;ver. n blocks used/n blocks allocated 
Following this line, an error message is displayed. If a 
blocking factor other than 1 is in use, an error message in the 
following form will be issued: 

ERROR STARTING AT VBN ni,n2 LBN ni,n2 - ERROR CODE -n 
Following the first error message, there should be one or more 
error messages indicating the exact block(s) in error. The 
second error message line(s) will be in the following form: 

ERROR AT VBN ni,n2 LBN ni,n2 - ERROR CODE -n 
If an ERROR STARTING AT line is displayed without one or more 
ERROR AT lines, a multiblock read operation on the selected 
device has failed, but the data blocks appear to be individually 
readable. 

If the VBN of the unreadable block listed in the ERROR AT line is 
beyond the block-used-count, the data portion of the file is 


readable. 


The negative number printed after the ERROR CODE message is 
usually -4 to indicate a device parity error. 


15.6 FILE ERROR REPORTING 
As VFY verifies a volume, error conditions are reported. Errors 
for a given file are preceded by a line that identifies the file 


in error. This line is formatted as follows: 


FILE ID nn,mm filename.filetype;version OWNER [uic] 


i es Fea | 


FILE ERROR REPORTING 


nn,mm 


Represents the unique file identification number assigned to 
the file by the system at file-creation time. 


filename 
Represents the filename. 
filetype 


Represents the file type (for example, .OBJ for object 
file). 


;version 

Represents the version number of the file. 
[uic] 

Represents the UIC for the file. 


This file identification line is followed by one or more of the 
following messages: 


I/O ERROR READING FILE HEADER-ERROR CODE -32 


Explanations VFY failed to read the file header for’ the 
specified file ID. The device is not mounted or is 
off-line, or the hardware has failed. 


BAD FILE HEADER 


Explanations VFY checks on the validity of the file header 
indicate that the header has been corrupted. 


MULTIPLE ALLOCATION n,m 


Explanation: The specified (double-precision) logical block 
number is allocated to more than one file. If this error 
occurs, a second pass automatically occurs that indicates 
all files that share each multiple-allocated block. The 
second pass is taken after all file headers are checked. 


BLOCK IS MARKED FREE n,m 
Explanations: The specified logical block number 1s 


allocated to the indicated file but is not marked as 
allocated in the storage allocation map. 
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BAD BLOCK NUMBER n,m 


Explanations The specified block number was found in the 
header for this file but is illegal for the device (out of 
range). This indicates a corrupted file header. 

FILE IS MARKED FOR DELETE 


Explanation: A system failure occurred while the specified 
file was being deleted. The deletion was not completed and 
the file header still exists. 

HEADER MAP ERROR 


Explanation: VFY detected an error in the header map area 
that also indicates a corrupted file header. 


The last error message for the file is followed by a summary line 
for that file, as follows: 
SUMMARY: MULT=nn, FREE=nn, BAD=nn. 
MULT 
Specifies the number of multiple block allocations. 
FREE 


Specifies the number of blocks marked free that should have 
been allocated. : 


BAD 


Specifies the number of errors encountered in the the map 
area of the file header. 


If the output for VFY is directed to a terminal and you do not 
wish to see the error messages for a given file, enter CTRL/O. 
This terminates the listing of error messages for that file that 
is, all messages but the summary line. 


15.6.1 Files Marked for Delete 


If a file has been marked for delete but the deletion process was 
not completed, you can either restore the file, if you still need 
it, or you can delete the file to recover the space it was 
occupying. This situation only occurs when the system crashes 
during file processing. 
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15.6.1.1 Deleting a File Marked for Delete - Files that 
are marked for delete can be deleted directly with PIP, once 
their unique file ID has been obtained by doing a validity check. 
The file ID appears as the first entry in the file identification 
line that precedes each list of file errors. The following 
example shows how the file ID is used with PIP to delete a file: 


S RUN SPIP 
PIP>/FI:12:20/DE 


In this example, the file with file ID 12,20 is deleted from the 
system device. PIP issues the error message: 


PIP -- FAILED TO MARK FILE FOR DELETE-NO SUCH FILE 


Since the file system denies the existence of files already 
marked for delete; however, the Fite 2s deleted. 


15.6.2 Deletion of Multiple-Allocated Blocks 


If the file structure contains multiple-allocated blocks, it is 
necessary to delete files until there are no such blocks. An 
automatic rescan of the volume identifies which files share which 
blocks. This rescan lists the files which contain the 
multiple-allocated blocks. Use this information to determine 
which, if any, of the files can be saved and then delete the rest 
with the PIP delete function. 


After the files have been deleted, VFY should be run once again 
to ensure that all of the files containing multiple-allocated 
blocks have been deleted. 


15.6.3 Recovering Lost Blocks 


To determine whether any blocks have been lost on a éfile- 
Structured volume, examine the last two lines of output from the 
Validity Check. The last two lines of output give the free space 


on the volume. The first line reports the amount of available 
Space according to the index file (that is, the number of blocks 
that are mot in use by any file in the index file). The second 


line reports the amount of available space according to the 
storage allocation bitmap. 


If there are no errors, the two figures should agree. If the 
index file indicates that more blocks are free than the storage 
allocation bitmap indicate, then those blocks are "lost" (they 
appear to be allocated, but no file contains them). 
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15.7. VFY ERROR MESSAGES 


The VFY error messages, their explanations, and suggested user 
actions are described below. 


VFY -- COMMAND SYNTAX ERROR 


Explanation: The command as entered does not conform to 
command syntax rules. 


User Action: Reenter the command line with the correct 
syntax specified. 


VFY -- CLOSE FAILURE ON BIT MAP 
or 

VFY -- CLOSE FAILURE ON INDEX FILE 
or 

VFY -- CLOSE FAILURE ON TEMPORARY FILE 
or 

VFY -- CLOSE FAILURE ON LISTING FILE 
or 

VFY -- I/O ERROR ON INPUT FILE 
or 

VFY -- I/O ERROR ON OUTPUT FILE 
or 

VFY -- I/O ERROR READING DIRECTORY FILE 
or 

VFY -- I/O ERROR WRITING FILE HEADER 
or 
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VFY -- FAILED TO CLOSE DIRECTORY FILE 
Explanation: One of the following conditions may exist: 
@ The device is not on-line 
@ The device is not mounted 
e The hardware has failed 


User Actions Determine which of the above conditions caused 
the message and correct that condition. Reenter the command 
line. 


VFY -- FAILED TO ALLOCATE SPACE FOR TEMP FILE 


Explanations: The volume specified for the temporary scratch 
file is full. 


User Actions Use PIP to delete unnecessary files and rerun 
VFY, or specify another volume as the scratch device when 
you reenter the command line. 

VFY -- FAILED TO ATTACH DEVICE 
or 

VFY -- FAILED TO DETACH DEVICE 


Explanation: The list file specified a terminal device. 
VFY was not able to attach or detach the device. 


User Action: Reenter the command line with a list file 
device that can be attached or detached. 


VFY -- FAILED TO ENTER FILE 
Explanation: One of the following conditions may exist: 
e VFY is not running under a system UIC 
@ The device is not on-line. 
e The device is not mounted. 


e The hardware has failed. 
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User Actions Determine which of the conditions caused the 
message and correct that condition. Reenter the command 


line. 

VFY -- FAILED TO FIND INDEXF.SYS;1 IN MFD-WILL OPEN INDEX BY FILE ID 1,1 
or 

VFY -- FAILED TO FIND BITMAP.SYS;1 IN MFD-WILL OPEN BITMAP BY FILE ID 2.2 


Explanations The Master File Directory has been corrupted. 


User Actions Copy the disk using the BRU Utility. 


VFY -- FAILED TO OPEN DIRECTORY FILE (See OPEN FAILURE error 
messages) 
VFY -- ILLEGAL DEVICE 


Explanation: The input device specified is something other 
than a disk or DECtape. 


User Actions: Reenter the command line with a mounted 
FILES-11 device specified. 


VFY -- ILLEGAL SWITCH 


Explanation: The switch specified is not a valid VFY switch 
or a valid switch is used illegally. 


User Actions: Reenter the command line with the correct 
Switch specified. 


VFY -- NO DYNAMIC MEMORY AVAILABLE - PARTITION TOO SMALL 
Explanation: VFY does not have enough buffer space to run. 


User Action: Run VFY in a larger partition (8K minimum). 


VFY -- OPEN FAILURE ON BIT MAP 
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or 


-~- OPEN FAILURE ON INDEX FILE 


or 


-- OPEN FAILURE ON LISTING FILE 


or 


-~- OPEN FAILURE ON TEMPORARY FILE 


or 


-- FAILED TO OPEN -DIRECTORY FILE 


-- FAILED TO OPEN FILE FOR READ CHECK 


Explanation: One of the following conditions may exist: 


e VFY is not running under a system UIC but should be. 


& The named file does not exist in the specified 
directory. 


@ The volume is not mounted. 
The specified file is read protected. 
e The specified file does not exist. 


User Actions Determine which of the above conditions caused 
the message and correct that condition. Reenter the command 


line. 
-- STORAGE CONTROL BLOCK (VBN1 of BITMAP.SYS) IS CORRUPTED 
Explanation: The Storage Control Block is corrupt. This is 


harmless, because only VFY and PIP /FR can examine the 
block. 


User Actions: Copy the disk using the Backup and Restore 
UtLLIty. 
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VFY -- THEY ARE STILL LOST, COULD NOT FIND DIRECTORY 
Explanation: UFD [1,3] did not exist on the volume. UFD 
[1,3] is the "lost files" directory. VFY enters all files 
found by the /LO switch into this directory. 


User Action: Use the DCL CREATE/DIRECTORY command to enter 
UFD [1,3] on the volume. 
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FUNCTIONS INITIATED BY DCL COMMANDS 


Most DCL commands initiate functions that are actually performed 


by some other system task or utility. Table A-1 lists these 
relationships. 


Table A-1: Functions Initiated by DCL Commands 


DCL Task/Utility Installed 
Command Filename Task Name 
ABORT LB: [ZZPRODCL]CATCH.TSK iaaCtA3 
ANALYZE/MEDIA LB: [ZZPRODCL]LCT.TSK ...MMV 
APPEND 

(Local files) LB: [ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: [ZZDECNET ]NFT.TSK NE 
ASSIGN LB: [ZZPRODCL]LCT.TSK ...MMV 
ASSIGN/TASK LB: [ZZPRODCL]CA2.TSK Soon? 
BASIC (Language dependent) see ore 
BROADCAST LB: [ZZSYS ]BRDCAST.TSK - « «BRO 
CANCEL LB: [ZZPRODCL]CATCH.TSK ..-CA3 
CLEAR LB: [ZZPROCDL]PRODCL.TSK se DCL 
COBOL (Language dependent) eeod 
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DCL Task/Utility Installed 
Command Filename Task Name 
CONTINUE LB: [ZZPRODCL]LCT.TSK ...MMV 
CONVERT LB: [ZZPRODCL]RMSCNV.TSK ses CNV 
COPY 

(Local files) LB: [ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: {ZZDECNET JNFT.TSK -. NFT 
CREATE 

(Local files) LB: [ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: [ZZDECNET ]NFT.TSK .. -NFT 
CREATE/DIR LB: {ZZPRODCL]LCT.TSK ...MMV 
DEASSIGN LB: [ZZPRODCL]LCT.TSK ...MMV 
DEFINE LBs (Z24PRODCLI LCT .TSk .- -MMV 
DELETE 

(Local files) LB: [ZZPRODCL]PIP.TSK Pere op 4 
(Remote files) LB: [ZZDECNET ]NFT.TSK ...NFT 
DIBOL (Language dependent) ‘ae DB 
DIFFERENCES LB: [ZZPRODCL]CMP.TSK » dae? 
DIRECTORY 

(Local files) LB:[ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: [ZZDECNET ]NFT.TSK ..-NFT 
DIRECTORY/ATTRIBUTES LB: [ZZPRODCL]RMSDSP.TSK iwc DOP 
DISMOUNT LB:[ZZPRODCL]LCT.TSK ...MMV 
DUMP LB: ({ZZPRODCL]DMP.TSK ée~ DMP 
EDI TABDT LB: [{ZZPRODCL]EDT.TSK Sarees a) Be 
EDIT/SLP LB: [ZZPRODCL]SLP.TSK ‘ae eae 
EDIT/PROSE LB: [ZZPRODCL]DCLPROSE.TSK »«sPRO 


(Starts the editor) 


EDIT/PROSE LB: [ZZSYS]CET.TSK CET 
(PROSE editor) 
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DCL Task/Utility Installed 
Command Filename Task Name 
EXIT LB: [ZZPRODCL]PRODCL.TSK ineDek 
FORMAT LB: [ZZPRODCL]LCT.TSK . MMV 
FORTRAN (Language dependent) ea 
HELP LB: {[ZZPRODCL]HELP.TSK »-HLP 
INITIALIZE LB: [ZZPRODCL]LCT.TSK . -MMV 
INSTALL LB: [ZZPRODCL]LCT.TSK . MMV 
LIBRARY LB: [ZZPRODCL]LBR.TSK i 4ebBR 
LINK LB: [ZZPRODCL]PAB.TSK ...PAB 
LINK/C81 (Language dependent) . «BLD 
(Invokes ...BLD, 

...PAB, and ...PIP) 

LOAD LB: [ZZPRODCL]LCT.TSK ...MMV 
“MACRO LB: [ZZPRODCL]PMA.TSK .. PMA 
MAIL LB: [ZZDECNET ]MAI.TSK -. MAI 
MOUNT LB: [ZZPRODCL]LCT.TSK ..MMV 
PASCAL (Language dependent) ...PAS 
PHONE LB: [ZZPRODCL]PHO.TSK . PHO 
PURGE 

(Local files) LB: [ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: [ZZPRODCL]NFT.TSK .. NFT 
REMOVE LB:[ZZPRODCL]LCT.TSK . MMV 
RENAME 

(Local files) LB:[ZZPRODCL]PIP.TSK ...PIP 
(Remote files) LB: [ZZPRODCL]NFT.TSK ...NFT 
REPLY LB: [ZZSYS]BRDCAST.TSK . BRO 


FUNCTIONS INITIATED BY DCL COMMANDS 


DCL Task/Utility Installed 
Command Filename Task Name 
RUN LB: [ZZPRODCL]LCT.TSK -. MMV 


(If the task is 
installed, DCL 
runs the task.) 


SET [DAY]TIME LB: [ZZPRODCL]CA2.TSK Seen 
SET DEFAULT LB: [ZZPRODCL]LCT.TSK ...MMV 
SET DEVICE LB: [ZZPRODCL]CA2.TSK sg Ce 
SET FILE 

(Local files) LB: [ZZPRODCL]PIP.TSK ey 2: 
(Remote files) LB: [ZZPRODCLT]NFT.TSK ...NFT 
SET HOST LB: [ZZDECNET]HST.TSK ...HST 
SET PRIORITY LB: [ZZPRODCL]CA2.TSK caniehe 
SET PROMPT LB: [ZZPRODCL]PRODCL.TSK sia DCU 


SET PROTECTION 


(Local files) LB: [ZZPRODCL]PIP.TSK ..-PIP 
(Remote files) LB: [ZZDECNET]NFT.TSK 53NET 
SET TERMINAL LB: [ZZPRODCL]CA2.TSK oo eC Ag 
SHOW ASSIGNMENTS LB: [ZZPRODCL]LCT.TSK 6 DV 
(Show a specific 

logical) 

SHOW ASSIGNMENTS LB: [ZZPRODCL]LNBDMP.TSK eo LG 
(Show all logicals) 

SHOW CLOCK_QUEUE LB: [ZZPRODCL]CA2.TSK menry Ge 
SHOW COMMON LB: [ZZPRODCL]CA2.TSK ua CR2 
SHOW [DAY]TIME LB: [ZZPRODCL]CA2.TSK mi eReZ 
SHOW DEFAULT LB: [ZZPRODCL]LCT.TSK ...MMV 
SHOW DEVICES LB: [ZZPRODCL]CA2.TSK Pere OF Wr 
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DCL Task/Utility Installed 
Command Filename Task Name 
SHOW LOGICALS LB: [{ZZPRODCL]LCT.TSK ...MMV 
(Show a specific 

logical) 

SHOW LOGICALS LB: [ZZPRODCL]LNBDMP.TSK 5.ee LG 


(Show all logicals) 


SHOW MEMORY LB:[ZZPRODCL]RMD.TSK -.-RMD 
SHOW PROTECTION LB: [ZZPRODCL]CA2.TSK ih? 
SHOW TASKS LB: [ZZPRODCL]CA2.TSK pe CAZ 
SHOW TASKS/ACTIVE LB: [ZZPRODCL]CA2.TSK .. -CA2 
SHOW TASKS/DYNAMIC LB: [ZZPRODCL]RMD.TSK ---RMD 
SHOW TASKS/INSTALLED LB: [{ZZPRODCL]CA2.TSK «e2CAZ 
SHOW TASKS/LOGICAL_UNIT LB: [ZZPRODCL]CA2.TSK ewe AZ 
SHOW TERMINAL LB: [ZZPRODCL]CA2.TSK se c€A2 
SHOW USERS 

(Local systems) LB: [ZZPRODCL]CA2.TSK se CRZ 
(Remote systems) LB: [ZZSYS]SHU.TSK :aeoHnU 
SPAWN LB: [ZZPRODCL]PRODCL.TSK Lue Dor 
START LB: [ZZPRODCL]CATCH.TSK Bree OF We: 
START /UNBLOCK LB: [ZZPRODCL]CATCH.TSK ..-CA3 
STOP/BLOCK LB: ([ZZPRODCL]CATCH.TSK ..-CA3 
SUBMIT/REMOTE LB: [ZZDECNET]NFT.TSK ae NET 


DCL 
Command 


TYPE 
(Local files) 
(Remote files) 


UNLOAD 
UNLOCK 


(Local files) 
(Remote files) 
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Task/Utility 
Filename 


LBs | GZPRODCEL PLP 
LB: [ZZDECNET ]NFT 


LB:{ZZPRODCL]LCT. 


LB:[ZZPRODCL]PIP. 
LB: [ZZDECNET]NFT. 


JTSK 
- TSK 


TSK 


TSK 
TSK 


Installed 
Task Name 


Ae eS = 
-NFT 


. MMV 


ee a 
NPT 


APPENDIX B 
ERROR MESSAGES 


This appendix lists two categories of error messages: general 
error messages and I/O error messages. 


NOTE 


Many system utilities issue error messages; these 
messages are explained elsewhere in the 
documentation set. 


B.1 GENERAL ERROR MESSAGES 


General error messages are common to many DCL commands. They can 
appear on your terminal screen preceded by a 3-letter code 
identifying the system component that detected the error. This 
can be the name of the utility (task) performing the command, or 
the command itself. This code appears here as yyy. 


Most of the general error messages with the word "expected" in 
them reprint the command on your terminal with a circumflex (*) 
pointing to the error. Sometimes the circumflex points to. the 
Character just past the last successfully parsed command element. 


Many of the explanations refer to the Radix-50 character set. 
The Radix-50 characters are the uppercase alphabet, the numerals 
0 through 9, the dollar sign (S$), the period (.), and the space. 


yyy -- Allocation failure - no contiguous space 


Explanations Not enough contiguous space is available on 
the output volume for the file being copied. 


User Action: Delete any files no longer required on _ the 
output volume and retry the command. 


YYY 


YYY 


YYY 


YYY 


see 4 


yy 


YYY 
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-- Allocation failure on output file 
or 
-- Allocation failure -- no space available 


Explanations: Not enough space is available on the output 
volume for the file being copied. 


User Action: Delete any files no longer required on _ the 
output volume and retry the command. 


-- A-Z expected 


Explanation: The command as typed included a nonalphabetic 
character. 


User Action: Check command for proper syntax and reenter. 
-~- A-Z and/or 0-9 expected 


Explanation: The command as typed included a 
nonalphanumeric character. 


User Action: Check command for proper syntax and reenter. 
-~- Bad error message 

Explanation: Some unusual condition has caused an error. 
User Action: Record the command that caused the error. and 
other information on activity at your terminal at the time. 
Then call your DIGITAL Customer Support Center. 


-- Bad use of wild cards in destination file name 


Explanation: A wildcard (*) was specified for an output 
file where it is not permitted. 


User Actions: Reenter the command with a complete and 
explicit file specification for the output file. 


-- Cannot find directory file 


Explanation: The command specified a directory not found on 
the current volume. | 


User Actions Reenter the command after checking for’ the 
correct directory and correct volume. 


bee's 


YYY 


Ya7y. 


ryy 


yyy 
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-- Cannot find files 


Explanation: The file or files specified in the command are 
not in the designated directory. 


User Action: Check the file specification and reenter’ the 
command line. 


-- Cannot rename from one device to another 


Explanation: The command attempted to rename a file across 
devices. 


User Actions: Use the COPY command to move the file from one 
device to another and rename it. 


-- Cannot truncate this filetype 
Explanation: The command attempted to truncate a file that 
cannot be truncated. Only files containing fixed-length, 


variable-length, or sequenced records can be truncated. 


User Actions Check to see if you have named the proper file 
and retry the command. 


-- Close failure on input file 
Or 
-- Close failure on output file 


Explanation: A file name in the command could not be 
properly closed. The file is locked by PIP. 


User Actions Use UNLOCK to unlock the file. Determine the 
cause of the error and correct it if you can. 


-- Command function not unique 


Explanation: The command as typed did not include 
sufficient characters to identify some command function. 


User Action: Retype command after checking proper syntax. 
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-- Command line incomplete 


Explanation: The command as typed is not a complete 
command. 


User Action: Retype command after checking proper syntax. 
-- Command syntax error 


Explanations The command did not conform to the syntax 
rules. 


User Actions Check command for proper syntax and _ reenter 
of oe 


~~ Conflicting qualifier 


Explanation: The command as typed included qualifiers that 
conflict with each other in their effect. 


User Action: Retype command after checking proper syntax. 
-- Contradictory qualifier 


Explanation: The command as typed included contradictory 
qualifiers, such as /DELETE and /NODELETE. 


User Action: Check for proper syntax and reenter command. 
-- Contradictory qualifier in key specification 


Explanation: The command included a contradictory qualifier 
in the key definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 
-- DCLSCOMMAND_ OPTIONS contains non-rad50 characters - deleted 


Explanation: The logical name DCLSCOMMAND_OPTIONS included 
a non-Radix-50 character where Radix-50 required. 


User Action: Recreate the logical name DCLSCOMMAND_OPTIONS, 
uSing proper’ syntax. The Radix-50 characters are _ the 
uppercase alphabet, the numbers 0 through 9, the dollar sign 
(S$), the period (.), and the space. 
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YyYyY -- DCLSEDITOR contains non-radix 50 characters. 


Explanation: The logical name DCLSEDITOR included a 
non-Radix-50 character where Radix-50 required. 


User Action: Recreate the logical name DCLSEDITOR, using 


proper syntax. The Radix-50 characters are the uppercase 
alphabet, the numbers 0 through 9, the dollar sign ($), the 
period (.), and the space. 

yyy -- Decimal number expected 


Explanation: The command included a number not in proper 
format. 


User Action: Check command for proper syntax and _ reenter 
with a decimal point (.) terminating the number. 


yyy -- Device invalid or not specified 


Explanation: The command specified an invalid device or no 
device at all when a device name is required. 


User Action: Check the devices on the system with SHOW 
DEVICES. Reenter command after checking for proper syntax. 
Determine the cause of the error and correct it if you can. 


yyy -- Device not in system 


Explanation: The command specified a device that is not in 
the current system. 


User Action: Check the devices on the system with SHOW 
DEVICES. Reenter command after checking for proper syntax. 


yyy -- Device not mounted/allocated 


Explanation: The command specified a device that is not 
properly mounted or allocated for the command to execute. 


User Action: Check the status of the device with SHOW 
DEVICES. Find the cause of the error and correct it 1f you 
can. 
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yyy - Device not terminal 


Explanation: The command specified a device other than a 
terminal where a terminal device name is required. TI: is 
not an acceptable terminal device name in all contexts. 


User Action: Reenter the command after checking for proper 
syntax. 


yyy -- Directory write protected 


Explanation: The command attempted to remove an entry from 
a directory that is privileged or from a directory ona 
device that is write-protected. 


User Actions Determine the cause of the error and correct 
it if you can. You may need to enable write access through 
the device hardware or change the protection for’ the 
directory. 


yyy -- Error dispatching command. DSW = ‘n’ 


Explanation: An error occurred that was not explicitly 
handled by DCL or some invoked task. 


User Action: Look up the DSW error code in the P/OS System 
Reference Manual. Determine the cause of the error and 
correct it if you can. 


YYY ~- Explicit output file name required 
Explanation: The command requires. an explore output 
filename. 


User Action: Reenter the command line in proper syntax and 
without wildcards. 


yyy -- Extraneous input 
Explanation: The command as typed included extraneous 
input. The circumflex (*) points to the error or just past 


the last successfully parsed command element. 


User Action: Reenter the command line in proper syntax. 
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yyy -- Failed to attach output device 
or 

yyy -- Failed to detach output device 
Explanation: An attempt to attach or detach a 
record-oriented output device, such as a terminal or line 
printer, failed. This error usually means the device is 


off-line or nonresident. 


User Actions Determine the cause of the error and correct 
it if you can. 


yyy -- Failed to create output UFD 
Explanation: The command failed to create an entry in a 
directory because the device was write-protected or because 
of a privilege violation. 
User Actions: Determine the cause of the error and correct 
it if you can. You may need to enable write access through 
the device hardware or change the protection for the 
directory. 

yyy -- Failed to delete file 
or 


yyy -- Failed to mark file for delete 


Explanations The command attempted to delete a protected 
file. 


User Action: Check for the proper file specification and 
default directory and reenter the command. 


yyy -- Failed to enter new filename 


Explanation: The command specified a file that already 
exists in the directory, or the directory is protected. 


User Actions Check for proper syntax; reenter command. 
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yyy -- Failed to find files 


Explanations The command specified a file or files that 
could not be found as specified. 


User Action: Check for proper file specifications and 
reenter the command. 


yyy -- Failed to get time parameters 


Explanations An internal system problem has occurred. 


User Actions Retry the command. If the error recurs, 
record the command that caused the error and other 
information on activity at your terminal at the time. Then 


call your DIGITAL Customer Support Center. 
yyy -- Failed to read attributes 


Explanation: The command specified a volume that is either 
corrupted or protected against access. 


User Actions You may be able to correct the error by making 
your defaults the same as the device and directory of the 
file you wish to affect. 


yyy -- Failed to remove directory entry 


Explanation: The command attempted to remove an entry from 
a directory that was either protected against access or ona 
write-protected device. 


User Action: Determine the cause of the error and correct 
it if you can. You may need to enable write access through 
the device hardware or change the protection for the 
directory. 


yyy -~- Failed to truncate file 


Explanations: The command specified a volume that 1s 
corrupted or is protected against access. 


User Action: You may be able to correct the error by making 
your defaults the same as the device and directory of the 
file you wish to affect. 
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yyy -- Failed to write attributes 


Explanation: The command specified a volume that is 
corrupted or is protected against access. 


User Actions You may be able to correct the error by making 
your defaults the same as the device and directory of the 
file you wish to affect. 


yyy -- Fatal I/O error 
Explanation: The command failed to execute because of some 
T/O error. This error can be caused by the unavailability 
of a device or of pool space, or by a device error. The 


device may be write-locked. 


User Action: Determine the cause of the error and correct 
it if you can. 


yyy -- File is lost 
Explanations: PIP has removed a file from its directory, 
Failed to delete it, and failed to restore the directory 


entry. 


User Action: Type @VERIFY to run the lost-file check to 
recover the filename. 


yyy -- Filename or filetype not specified 
Explanation: The command as typed did not clearly specify a 
filename and file type where one or the other or both is 
required. This error can be caused if you do not leave a 


Space in front of a file specification that is a parameter. 


User Action: Retype command after checking for proper 
syntax. 


vyy -- File not locked 


Explanation: An UNLOCK command specified a file that is not 
locked. 


User Actions Check for the proper file specification and 
reenter the command. 
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we Pile specification €ither invalid. or not ‘specified 
Explanation: The system could not read a file specification 
included in the command. This error often results from a 
typing mistake or typing the command in the wrong format. 


User Action: Check for proper syntax and reenter’ the 
command. 


-- File specification list not available for RMS-11 


Explanation: A command to an RMS-11 utility included more 
than one input file specification. 


User Action: Check for proper syntax and reenter command. 
-- File version number not specified 


Explanation: The command requires a file version number’ to 
be specified. 


User Action: Reenter command after checking for. proper 
syntax. 


-- Function not unique 


Explanation: The command as typed did not include 
sufficient characters to identify some function. 


User Action: Retype the command but include more 
characters. 


-- Get command line - Bad @ filename 


Explanation: The command specified an illegal indirect 
command file. 


User Actions: Check for proper file specification and 
reenter the command. 


-- Illegal command 


Explanation: The command, which is the first word on _ the 
command line, is not part of DCL. 


User Action: Check command for proper syntax and reenter. 
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yyy -- Illegal concealed device specification 


Explanation: The command named a concealed device in an 
illegal format or contained some other syntax error. 


User Action: Check command for proper syntax and _ reenter. 
Device names are two alphabetical characters followed by an 
octal number and a colon. 


yyy -- Illegal device 


Explanation: The command named a device in an illegal 
format or contained some other syntax error. 


User Action: Check command for proper syntax and _ reenter. 
Device names are two alphabetical characters followed by an 
octal number and a colon. 


yyy -- Illegal filespec 


Explanation: The command required a file specification that 
was not present. 


User Action: Check command for proper syntax and _ reenter. 
See Chapter 2 for a complete description of a file 
Specification. Perhaps some other command element is being 
parsed as a filespec. Use the prompting version. 


yyy -- Illegal or contradictory qualifier 


Explanation: One or more qualifiers to the command are in 
conflict, or are in error. 


User Action: Check command for proper syntax and reenter. 
yyy -- Illegal protection code 


Explanation: The command specified a protection code in an 
improper format. 


User Action: Check command for proper syntax and reenter. 
yyy -- Illegal qualifier value 


Explanation: The command as typed included an improper 
argument to a qualifier. 


User Action: Check command for proper syntax and _ reenter. 
In DCL, an argument is preceded by a colon (:). 
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yyy -- Illegal use of wildcard character 
Explanation: The command included a wildcard (* or %) in a 
file specification in a way that would result in 
unpredictable or inconsistent output. 


User Action: Check command for proper syntax and _ reenter. 
You may not be able to use the wildcard. 


yyy -- Illegal task name 


Explanation: The command named a task using a task name in 
an illegal format. 


User Action: Check command for proper syntax and reenter. 
Task names include as many as Six Radix-50 characters. 


YYyY -- Input device must be a directory device 
Explanation: The command as typed specified a device that 
1s not a directory device, such as a printer. Directory 


devices are those on which FILES-11 volumes with directories 
can be mounted. 


User Action: Correct syntax and reenter command. 
yyy -- Input files have conflicting attributes 


Explanation: Warning message. The command Operation 
completed, but the files named had conflicting attributes. 


User Actions Use DIRECTORY/ATTRIBUTES co find the 
attributes of all input and output files involved. 
Determine if the conflict causes any difficulty. 


yyy -- Invalid command function 


Explanation: The command as typed requested a function that 
is not valid for that command. 


User Action: Check command for proper syntax and _ reenter 
Lt. 

yyy -- Invalid command parameter 
Explanation: The command as typed included a parameter that 
is not valid. In DCL, a parameter is either entered in 


response to a prompt or preceded by a space. 


User Action: Check command for proper syntax and reenter. 


YYY 


YY 


YYY 


YYY 


YY 


YYY 
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-- Invalid file specification list 

Explanation: The command included a list GE file 
Specifications in an invalid format. In general, file 
Specifications in lists should be separated by commas and, 
optionally, blanks. 

User Action: Retype command after checking proper syntax. 
-- Invalid file specification qualifier 

Explanation: The command included a qualifier to ae file 
Specification that was not valid. In DCL, a qualifier is 


preceded by a slash (/). 


User Action: Check for proper syntax and retype the 
command. 


-- Invalid terminal specified 


Explanation: A command directed to a specific terminal 
named the terminal in an improper format. 


User Action: Check the name of the terminal using SHOW 
DEVICE and reenter the command with the proper format. 


-- Invalid time or date 


Explanation: The command specified a clock or calendar 
field, or both, incorrectly. 


User Action: Check for proper syntax and retype the 
command. 


-- Invalid UIC specified 
or 
-- Invalid directory specified 
Explanation: The command specified one of the following: 


® A named directory containing a nonalphanumeric string or 
more than nine characters 


@® A numbered directory containing 0, a number including 8 
or 9, or a number greater than 377 (octal) 


User Action: Check for proper syntax and retype command. 
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yyy -- I/0 error on input file 


YYY 


YY Y. 


yyy 


yYY 


yyy 


or 
-- I/O error on output file 
Explanations One of the following conditions exists: 
e The device is not on line. 
e he device is not mounted. 
@e The hardware has failed. 
e The output volume is full. 
e The input file is corrupted. 


User Actions Determine the cause of the error and correct 
it 1f ‘you can. 


-- Key position size or number not specified 

Explanation: The command failed to include the size or 
number of a key position in the key definition argument to 
the /KEY qualifier. 

User Action: Check command for proper syntax and retype it. 


-- Key specification out of Sequence 


Explanation: The command included improper syntax in the 
key definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 
-- More command parameters than permitted 


Explanation: The command as typed included too many 
parameters. 


User Action: Check command for proper syntax and reenter. 
-- No such file 


Explanation: The command requested operations on ae file 
that does not exist. 


User Action: Make sure you have named the file properly. 


Check your defaults to be sure you are looking in the right 
directory on the right device. You may have made a typing 
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YYY 


YYY 


YYY 


Seed 


YYY 


1yy 
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error. If the desired file is in fact not present, find out 
why it is not present and proceed accordingly. 
-- Not a directory device 


Explanation: A directory-oriented command named a device 
that does not have directories, such a line printer. 


User Actions: If you can, reenter the command without 
specifying a directory. 


~- Numeral expected 
or 
-- Numeral required 


Explanation: Command included nonnumeric characters in a 
position where numerals are required or expected. 


User Action: Check command for proper syntax and reenter. 
-- Octal number expected 


Explanation: The command included a number with an 8 or 9 
where an octal number was expected. 


User Action: Check command for proper syntax and reenter. 
-- Open failure on file 


Explanation: The system could not open a required file for 
some reason. 


User Action: Check the directory to be sure that the _ file 
is present, not locked, and in the proper format. If the 
file is locked, it may be corrupted or contain bad data. 
Determine the cause of the error and correct it if you can. 


-- Output device must be a directory device 

Explanation: The command as typed specified a device that 
is not a directory device, such as a printer. Directory 
devices are those on which FILES-11 volumes with directories 


can be mounted. 


User Action: Correct syntax and reenter command. 


GENERAL ERROR MESSAGES 


yyy -- Primary key not specified 
Explanation: A command affecting an indexed file failed to 
include a primary key. In many such commands, you cannot 
Specify any action on an alternate key without first 
identifying the primary key. 
User Action: Check for proper syntax and reenter command. 


yyy -- Qualifier inconsistent with compiler 


Explanation: A compiler command included a qualifier not 
acceptable by that compiler. 


User Action: Check the command for proper syntax and try it 
again. 


yyy -- Qualifier not available for this command format 


Explanation: The command included a qualifier that is 


invalid in the current context of the command. The context 
is usually determined by some other qualifier in _ the 
command. 


User Action: Reenter command after checking for proper 
syntax. 


yyy -- Qualifier not unique 
Explanation: The command as typed did not include 


sufficient characters to identify some qualifier. In DCL, 
qualifiers are preceded by a slash (/). 


User Action: Retype _ the command, but include more 
characters. 

yyy -- Qualifier value invalid here 
Explanation: The commands as typed included an 
inappropriate argument to a qualifier. In DCL, an argument 


is usually preceded by a colon (:). 


User Action: Check command for proper syntax and reenter. 


GENERAL ERROR MESSAGES 


yyy -- Radix-50 expected 


Explanation: The command included a non-Radix-50 character 
where Radix-50 required. 


User Action: Reenter the command using proper syntax. The 
Radix-50 characters are the uppercase alphabet, the numbers 
QO through 9, the dollar sign ($), and the period (.). 

yyy -- Repeated command parameter 
Explanation: The command as typed included one parameter 
more than once. In DCL, a parameter is preceded by a blank 


or prompt. 


User Action: Retype command after checking for proper 
syntax. 


YYY -- Repeated key specification 
Explanation: The command as typed included the same _ key 
specification more than once in the key definition argument 


to the /KEY qualifier. 


User Action: Retype command after checking for proper 
syntax. 


yyy -- Repeated keyword in key specification 
Explanation: The command as typed included the same keyword 
more than once in the key definition argument to the /KEY 


qualifier. 


User Action: Retype command after checking for proper 
syntax. 


yyy -- Repeated qualifier 


Explanation: The command specified the same qualifier more 
than once. In DCL, a qualifier is preceded by a slash (/). 


User Action: Reenter command after checking the syntax to 
see if it is right. 
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yyy -- Required parameter not specified 
Explanation: The command cannot execute without required 
parameters, such asa file specification or attribute. In 
DCL, a parameter 1s preceded by a blank or prompt. 


User Action: Retry the command, using the prompts. DCL 
prompts for all required parameters. 


yyy -- Required qualifier not specified 


Explanation: The command requires a qualifier that it does 


not include. In DCL, a qualifier is preceded by a slash 
(/)- 
User Action: Check for proper syntax and reenter’ the 
command. 

yyy -- Required qualifier value not specified 


Explanation: A qualifier to the command requires that you 
state a numerical argument. In DCL, an argument is usually 
preceded by a colon (:). | 


User Action: Retype command after checking for proper 
syntax. 


yyy -- Required value not specified for position size or number 


Explanation: The command failed to include a required value 
in the key definition argument to the /INDEXED qualifier. 


User Action: Check command for proper syntax and reenter. 
yYY -- Sorry, line too long 


Explanation: DCL commands are translated for execution by a 


system task or utility. This error is caused by a 
translated command line that the destination task cannot 
handle. 


User Action: Check command syntax to see if you are 
specifying elements that can be defaulted. Check to see if 
you can enter the command twice with different qualifiers 
instead of entering one command. 
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yyy -- Sorry, low pool 


Explanation: The command could not execute because of 
insufficient space in the system pool (dynamic storage 


region). 
User Action: The pool is the Executive’s data base. In 
general, each task, including commands, uses a certain 


amount of pool. If the pool is full or badly fragmented, 
there may not be sufficient space for the command to 
execute. Usually, pool problems clear up spontaneously if 
you wait. 


Retry the command after an interval. You should not attempt 
to execute any other task, not even an ABORT, when the pool 
is low. The task also absorbs pool. 


yyy -- Sorry, task active 


Explanation: The command required some action that cannot 
be taken on an active task. 


User Action: Determine the cause of the error and correct 
it if you can. Check the task with the various SHOW TASK 
commands, or SHOW MEMORY. 

yyy -- Sorry, task not installed 


Explanation: The command attempted to invoke a task that 
was not installed. 


User Action: Try running the task with a command in the RUN 
S form. Determine the cause of the error and correct it if 
you can. 


yyy -- String argument too long 


Explanation: There are too many characters in the argument 
you entered. 


User Action: Enter the command again with fewer characters 
in the argument. 


yYYY -- syntax error 
Explanation: The command included some error in typing or 
specification, such as a letter where a number should 
appear. 


User Action: Check for proper syntax and reenter command. 
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yyy -- Version must be explicit or "x" 
Explanations The command syntax requires that the version 
number of the file must be specified explicitly or as a 
wildcard ( * ). 


User Actions Reenter the command with the version number 
correctly expressed. 


yyy -- Wildcards not permitted 


Explanation: Command included a wildcard (* or %) in a 
context where it is not permitted. 


User Action: Check for proper syntax and reenter command. 
yyy -- Zero value not valid for key size or number 


Explanation: The command included a zero value in the _ key 
definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 


B.2 I/Q0 ERROR MESSAGES 


I/O error messages are returned as codes. Table B-1 lists P/OS 
I/O error codes. Only partial abbreviations (xxx) are listed; 
the complete abbreviation is IE.xxx. The octal number listed 1s 
the low-order byte of the complete value (2’s complement of the 
decimal number). 
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Table B-1: I/O Error Messages 


Abbre- --Error No.-- 
viation Decimal Octal Meaning 


. BAD -1 377 Bad parameters 
Lee -2 376 Invalid function code 
. DNR -3 375 Device not ready 
. VER -4 374 Parity error on device 
.ONP -5 373 Hardware option not present 
~SPC -6 372 Invalid user buffer 
as .DNA -7 eye Device not attached 
: .DAA -8 370 Device already attached 
. DUN -9 367 Device not attachable 
. EOF -10 366 End-of-file detected 
. EOV -11 365 End-of-volume detected 
. WLK -12 364 Write attempted to locked unit 
. DAO -13 363 Data overrun 
.SRE -14 362 Send/receive failure 
. ABO -15 361 | Request terminated 
. PRI -16 360 Privilege violation 
-RSU -17 357 Shareable resource in use 
-OVR -18 356 Invalid overlay request 
.BYT -19 35 Odd byte count or virtual address 
. BLK -20 354 Logical Block Number too large 
. MOD -21 353 Invalid UDC module number 
. CON -22 352 UDC connect error 
. NOD -23 351 Caller’s nodes exhausted 
.DFU -24 350 Device full 
~LFU -25 347 Index file full 
.NSF ~26 346 No such file 
. LCK -27 345 Locked from read-write access 
.HFU ~28 344 File header full 
WAC -29 343 Accessed for write 
~CKS -~30 342 File header checksum failure 
. WAT -31 341 Attribute control list format error 
.RER ~32 340 File processor device read error 
.WER =33 337 File processor device write error 
. ALN -34 336 File already accessed on LUN 
. SNC -~35 335 File ID, file number check 
~SQC -36 334 File ID, sequence number check 
.NLN -37 333 No file accessed on LUN 
.CLO -38 332 File was not properly closed 
.NBF -39 331 File buffer space unavailable 


Abbre- 
viation 


-RBG 
-NBK 
- ILL 


«BIP 
»RAC 
- RAT 
- RCN 
ebCE 
.2DV 
-FEX 
-BDR 
- RNM 
.BDI 
. FOP 
. BNM 
- BDV 
- BBE 
- DUP 
- OTK 
. FHE 
-NFI 
-ISQ 
- BOT 
-BVR 
- BHD 
~OFL 
~BCC 
. ONL 
- NNN 
-NFW 
- BLB 
. TMM 
-NDR 
- URJ 
~NRJ 
-BTF 
- NNC 
-NNL 
.NLK 


-~-Error 
Decimal 


-40 
-41 
-42 


-43 
-44 
-45 
-46 
-47 
-48 
-49 
-50 
~51 
-52 
-~53 
-54 
-55 
-56 
-57 
-58 
-59 
-60 
-61 
=62 
-63 
-64 
-65 
-66 
=O] 
-68 
-69 
-70 
=). 
-72 
~13 
-74 
-716 
-77 
-78 
-/9 
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No.-- 
Octal 


3:30 
327 
326 


3:25 
324 
323 
322 
324 
320 
317 
316 
S315 
314 
315 
ey 
311 
310 
307 
306 
305 
304 
303 
302 
301 
300 
2/7 
276 
275 
274 
24 
ad 
Zi 
270 
267 
266 
264 
263 
262 
261 


Meaning 


Invalid record size 

File exceeds space allocated, no blocks 
Invalid operation on file 
descriptor block 

Bad record type 

Invalid record access bits set 
Invalid record attribute bits set 
Invalid record number-too large 
Internal consistency error 
Rename--two different devices 
Rename--a new filename already in use 
Bad directory syntax 

Cannot rename old file system 

Bad directory syntax 

File already open 

Bad filename 

Bad device name 

Bad block on device 
Enter-duplicate entry in directory 
Not enough stack space (FCS or FCP) 
Fatal hardware error on device 
File ID was not specified 

Invalid sequential operation 
End-of-tape detected 

Bad version number 

Bad file header 

Device off line 

Block check, CRC, or framing error 
Device on line 

No such node 

Path lost to partner 

Bad logical buffer 

Too many outstanding messages 

No dynamic space available 
Connection rejected by user 
Connection rejected by network 

Bad tape format 

Not ANSI ’D’ format byte count 

No data available 

Task not linked to specified 
LCS/ICR. interrupts 


Abbre- 
viation 


-NST 
- AST 
-FLN 


-ITES 
-PES 
- ALC 
- ULK 
-WCK 
-NTR 
-REJ 
.FLG 
-DSQ 
- [QU 
~RES 
. TML 
-NNT 
. TMO 
. CNR 
foot 
-MITI 
-oPI 


--Error 


Decimal Octal 


-80 
-80 
-81 


-82 
-83 
-84 
-85 
-~86 
-87 
-88 
-89 
-90 
-91 
-92 
-93 
-94 
“95 
-96 
=98 
-99 
-100 
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No.-- 


260 
260 
257 


256 
255 
254 
Zo3 
252 
251 
250 
247 
246 
245 
244 
243 
242 
241 
240 
236 
235 
234 


Meaning 


Specified task not installed 
No AST specified in connect 
Device off line when off-line 
request issued 

Invalid escape sequence 
Partial escape sequence 
Allocation failure 

Unlock error 

Write check failure 

Task not triggered 

Transfer rejected by receiving CPU 
Event flag already specified 
Disk quota exceeded 
Inconsistent qualifier usage 
Circuit reset during operation 
Too many links to task 

Not a network task 

Timeout on request 

Connection rejected 

Unable to size device 

Media inserted incorrectly 
Spindown ignored 


APPENDIX C 
SAMPLE EDT INITIALIZATION FILE 


The Edit command initializes EDT using a default EDT 
initialization file. The complete file specification for this 
initialization file is: 


LB000:[{1,2]EDTSYS.EDT 


You can edit this initialization file to include commands that 
are Similar to those found in the example in this appendix (refer 
to the EDT Quick Reference Guide for further information on 
creating EDT initialization files). 


You can maintain one or more EDT initialization files in 
directories other than [1,2]. However, you must use the /COM 
qualifier in the EDT command line to use any command file not 
found in the default directory. | 


A sample initialization file follows. 


SET SCREEN 79 ! Sets screen width to 79 characters. 

SET CURSOR 2:15 ! EDT will scroll file, if cursor is moved before line 
! 2 or after line 15. 

SET WRAP 70 ! Sets the maximum line length of n character 
! positions (70 in this example). As you enter 
! text, EDT will attempt to wrap a full word that 
! extends beyond character position 70. 

SET NOTRUNCATE ! Displays lines that extend beyond the line width set 
! by SET SCREEN 79. 

SET TAB 3 ! Sets the first tab stop at character position 3; all 
! other tab stops are set at multiples of 8 after the 


! first tab stop. 


DEFINE KEY GOLD 


DEFINE KEY GOLD 


DEFINE KEY CONTROL 


SET MODE CHANGE 


AS: “EXT EXIT.” 

Defines the keystroke sequence GOLD + E 
as the EXIT command in Change mode. 

AS "EXT QUIT." 


Defines the keystroke sequence GOLD + Q as 
the QUIT command (used only in Change mode' 


AS "+DC ADV C UNDC C." 


This keystroke sequence 
reverses the position of two letters. 


Causes EDT to begin the editing session in 
Change mode. 


APPENDIX D 
USING PRO/TOOL KIT MCR 


This appendix gives you the information you need to use PRO/MCR 
on the Professional Operating System (P/OS). It introduces you 
to MCR and provides a summary of the MCR commands. You should be 
familiar with both P/OS and PRO/DCL before you read this. 


D.1 MCR ON P/OS 


The Monitor Console Routine (PRO/MCR) serves as ae terminal 
interface between you and the Professional Operating System. 


PRO/MCR provides functions for two types of users: privileged 
and nonprivileged. If the PRO/Tool Kit has been installed, 
PRO/MCR provides privileged users with functions that control and 
modify system operation and permit program development and system 
maintenance. PRO/MCR provides nonprivileged users with functions 
that permit program development and terminal maintenance. 


Please note that MCR is available in P/OS only if you specify MCR 
in the logical name DCLSCOMMAND_OPTIONS while executing the P/OS 
Command Language or PRO/Tool Kit application. Chapter 5 explains 
how to define the logical name DCLSCOMMAND_OPTIONS to allow you 
to control the way commands are interpreted in PRO/DCL. The 
remainder of this appendix assumes that you have defined the 
logical name DCLSCOMMAND_OPTIONS and equated it to MCR. 


D.1.1 The MCR Command Line 


Command lines can be passed to MCR in one of two ways. If the 
logical name DCLSCOMMAND_OPTIONS is not present, you can enter an 
explicit MCR command at the DCL prompt by prefixing the command 
with MCR. Additionally, if you define the logical 
DCLSCOMMAND_OPTIONS and equate to it the value of MCR, you can 
enter any legal MCR command. 


MCR ON P/OS 


An MCR command line consists of three components: a command 
name, command parameters, and a line terminator. It is not 
necessary to type the entire command name when you issue a 
command. MCR uses only the first three letters of command names. 
You follow the command name with command parameters and ae line 
terminator (the RETURN key). The DO key can also be used as a 
line terminator. 


For example, you can type the CANCEL command as follows: 


S CAN taskname<RET> 


The variable taskname is a parameter for the CANCEL command. 
<RET> signifies the RETURN key, the line terminator. As in this 
example, you often type only the first three letters of a command 
name. However, some commands have 3-letter acronyms as command 
names. For example, the names for the ASSIGN and USER FILE 
DIRECTORY commands are ASN and UFD, respectively. 


With most MCR commands, you can specify the full form of the 
command name, but this is unnecessary because MCR only uses the 
required first three letters. However, if you want to make the 
intent of the command clear to someone else, you can type the 
full command name. For example: 


S CANCEL taskname<RET> 


A space, tab, or slash signals the end of the command name; 
therefore, no spaces, tabs, or slashes are allowed within the 
command name itself. For example, this command syntax is 
permissible: 


S OPENREGISTER address 


This command syntax is not: 


S OPEN REGISTER address 


Typically, a command parameter is a task name, the name of a 
file, or a device specification. A parameter can be modified by 
a keyword. 


D.1.1.1 Prompting - MCR uses two kinds of prompts to indicate 
that a terminal is waiting for your input: the default prompt 
and task prompts. 


The default prompt ’S$’ at the beginning of a new line indicates 


that the terminal is waiting to accept your input. Whatever you 
type will be directed to MCR. (An abnormal condition can occur, 
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however, if a task either solicits input or attaches to the 
terminal without displaying a task prompt.) When MCR receives a 
command line it identifies it, analyzes it, and _ responds 
appropriately to the command. 


When MCR activates a task to service a command, the task normally 
prompts as follows: 


tsk> 


The variable tsk is a three-letter task name. (All DIGITAL 
system tasks identify themselves by a 3-character prompt and user 
tasks should do the same.) 


D.1.1.2 Correcting Mistakes with the Single Line Editor - While 
entering commands in response to the default prompt you can use 
the Single Line Editor (SLE). For example, if you make a mistake 
before pressing the RETURN (or DO) key, you can correct it 
without retyping the entire command. Press the LEFT ARROW key 
until the cursor is to the right of any character(s) you want to 
change, delete the part you do not want with the <X] key, = and 
retype. To add a part you left out, move the cursor to that 
place and type the omitted part. The rest of the command will 
move to the right to make room. 


If you make a mistake after you pressed the RETURN (or DO) key, 
press the UP ARROW key. The command will be redisplayed for 
changing. You can display up to nine previous commands this way. 
You can use the DOWN ARROW key to display the next command. 


While you are entering commands, the following function keys are 


also available: 


@® CANCEL, CTRL/C, or CTRL/U: erases the current command 
so that you can start over. 


e F113: erases from where the cursor is to the end of 
line. 


@ REMOVE: deletes the character that the cursor is 
currently on. 


@® cCTRL/E: places the cursor at the end of the command 
line. 


@e cCTRL/H: places the cursor at the beginning of the 
command line. 
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@ HELP: inserts the text HELP at the beginning of the 
command line. 


@ EXIT or MAIN SCREEN: deletes any current command and 
enters the EXIT command. 


D.1.1.3 Keywords - Some MCR commands use keywords that affect a 
command parameter. A keyword consists of a slash (/) followed by 
a keyword. A keyword may be followed by an optional equal _ sign 
(=) and value. For example: 


/keyword[=value] 


A keyword modifies the action of the command. You can apply a 
keyword directly to the command or to a command parameter, 
depending on the command. If the keyword follows the command 
name, it modifies the action of the command. If the keyword 
follows a parameter, it modifies the action of the parameter. 


For example, the INSTALL command requires a file name parameter 
that specifies the task to be installed. You can append keywords 
to this filename. One such keyword, /TASK, specifies the name 
under which the task is to be installed. For example: 


S INS BOB.TSK/TASK=AMBER<RET> 


This command installs the task image file BOB.TSK with the name 
AMBER. When you want to use the task, you invoke it with the 
name AMBER. 


If you want to specify multiple keywords with a command, you’ can 
enter the keywords in the order in which you want the commands 
processed. Because keywords are command-specific, the keywords 
for each command are defined in each command description. 


D.1.1.4 Comments - MCR treats a line of text as a comment if the 


first character is a semicolon (;). In addition, you can delimit 
comments within a command line by uSing an exclamation point (!). 
The first exclamation point starts the comment, and the second 
exclamation point or the line terminator ends the comment. MCR 
ignores all text between the two exclamation points. For 
example: 


S : THIS LINE IS A COMMENT 
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S TAL !THIS IS A COMMENT STRING! RMD 


Comments are especially useful for clarifying commands in 
indirect command files. 


If a semicolon or exclamation point is part of a command line, 
you must place these characters within quotation marks. 


D.1.2 The MCR Interface 


MCR parses your typed input to determine what the command line is 
requesting, then responds accordingly. To service a request, MCR 
either processes the command or activates an independent task. 


The required three letters of the command line are its most 


Significant part. The following procedures detail how MCR 
processes each command: 


1. MCR searches a table containing names of commands” that 
MCR recognizes. If the table contains a command that 
matches the one you have typed, MCR starts the secondary 
task that processes the command. 


2. If the table does not contain a matching command, MCR 


prefixes three dots (...) to the command name and 
searches the System Task Directory (STD) for a task by 
that name (that is, ...tsk). MCR returns an error if 
the STD does not contain the specified task. If there 
are more keywords in the logical name 
DCLSCOMMAND_OPTIONS the command is passed to the next 
process. 


On P/OS, MCR first looks for an installed version of 
tskTnn and requests the Executive to run it. If an 
installed version does not exist, MCR creates a 
temporary STD entry, names the task tskTnn, and requests 
the Executive to run the task. When tskTnn exits, the 
Executive automatically deletes its STD entry. 


D.2 P/OS MONITOR CONSOLE ROUTINE (MCR) COMMANDS 


In this section, (P) indicates that a command format or keyword 
is privileged and (NP) indicates that it is a nonprivileged 
command. Note, however, that some commands are _ both. A 
privileged user can execute a nonprivileged command. 
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D.2.1 ABO 


ABORT (NP,P) 


The ABORT command forces an orderly end to the specified running 


task. Nonprivileged users can abort a nonprivileged task if the 
task was requested from the terminal that issued the ABORT 
command. Nonprivileged users can also abort privileged tasks 


requested from the issuing terminal if the tasks have requested 
an AST services routine with the SREXS form of the SPECIFY 
REQUESTED EXIT AST Executive directive. Privileged users’ can 
abort any task. 


Syntax 


ABORT taskname [/TERM=ttnnn: ] 


taskname 
The name of the task to be aborted. If you omit the 
taskname, the command attempts to abort the task ttnn. (The 
variable nn is the octal unit number of the issuing 
terminal.) 


Likewise, if you specify only the first three characters of 
the taskname, ABORT defaults the taskname to tskTnn. 


/TERM=ttnnn: 


A privileged keyword that aborts a task requested from a 
terminal other than the one issuing the ABORT command. 


ACT 


D.2.2 ACT 


ACTIVE (NP) 
The ACTIVE command displays the names of all active tasks whose 
TL: is the same as the terminal from which the command is 
entered. 
Syntax 

ACTIVE [/keyword] 


/ALL 


Displays the names of all active tasks that are currently in 
the system. 


/TERM=ttnnn: 


Displays the names of all active tasks for the terminal 
Specified by ttnnn: 


ALT 


D.2.3 ALT 


ALTER (P) 


The ALTER command changes the static or running priority of an 
installed task. 


Syntax 
ALTER taskname [/keyword(s) ] 

taskname 

The name of the task whose priority is to be altered. 
/PRI=n 

Changes the task’s static and running priority. 
/RPRI=n 

Changes the task’s running priority only. 
/TERM=ttnnn: 


Alters the priority of a task not initiated from the issuing 
terminal. 


The priority can be from 1 to 250 (decimal). The system assumes 
that the priority value you specify is octal unless you include a 
period (.) after the value. 


ASN 


D.2.4 ASN 


ASSIGN (NP,P) 


The ASSIGN command creates, deletes, or displays logical name 
assignments. A logical name assignment associates a user-chosen 
name with a physical device, a pseudo device, a logical device, a 
part of a Files-11 file specification, all of a Files-11 file 
Specification, or another logical name. 


The system pairs’ logical names and their corresponding 
equivalence names grouped in the following logical name tables: 


e The user logical name table contains logical name 
entries that are local to a particular application. 
When the application exits, the contents of the user 
logical name table are deleted. Use the /USER keyword 
to make an entry in the user logical name table. 


e The session logical name table contains logical name 
entries that are local to a particular user. By default 
the ASN and DFL commands place a logical name in _ the 
session logical name table. You can also use the 
/SESSION keyword to make an entry in the session logical 
name table. 


@e The system logical name table contains entries that can 
be accessed by any task in the system. You use the 
/SYSTEM or /GBL keyword to make an entry in the system 
logical name table. 


When the system encounters a logical name, it searches’ the 
logical name tables in this order: user, session, and system. 
The system uses the first match as the equivalence name for the 
logical name. When it finds an equivalence name, the system 
substitutes the equivalence name for the logical name in the file 
specification. This is called logical name translation. 


Logical name translation can be iterative. Iterative translation 
means that the system repeats the process of logical name 
translation until it resolves a logical name to its original 
device or file specification. 


You can limit the epanecete on of logical names to one iteration 
with the /FINAL keyword. 


The system limits logical name translation to eight levels. LE 
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you define more than eight levels or create a circular definition 
of a logical name, an error will occur if you try to use the 
logical name iteratively. 


If you forget the equivalence name assigned to a logical name, 
use the ASSIGN command to display the current assignment. Type 
ASN and the logical name, then press the RETURN key. 


You can use logical names to define concealed devices. Concealed 
devices are used to associate a logical name with a device and, 
optionally, a directory name. Subsequent use of the logical name 
results in the device and directory being used as the Master File 
Directory (MFD) for all file operations. The following is an 
example of a concealed device. 


SASN _DW002:[CHARLES. ]=CD001: /CONCEALED 
SPIP CD001:[USERFILES]/LI 


Directory CD1:[USERFILES] 28-JUN-85 11:20 
EXAMPLE. DAT 4 27-JUN-85 17:21 


As a result of the ASN command and the invocation of the PIP 
utility task, the contents of the directory [CHARLES.USERFILES] 
on the device DW002: was displayed to the terminal issuing the 
commands. 


The logical name DWO0O1: is another example of a concealed 
logical name. 


If the /CONCEALED keyword is specified, the physical device name 
must be of the form ddnnn: and the logical device name of the 
form _ddnnn:[dirspec.] where dirspec is optional. 


Syntax 


The ASSIGN command has three types of syntax. Following is a 
brief list of these formats, and a description of the terms used 
in each, including descriptions of optional keywords. 


s)] ‘Makes logical assignments 
] 'Deletes logical assignments 
'Displays logical assignments 


ASN =[1n:][/keyword( 


ASN en:=Il1n: [/keyword 
S 
ASN [ln:][/keyword(s) 


( 
) 


The terms shown in the ASN command formats have the following 
meanings: 


ASN 


en 
The equivalence name (the name or specification to which you 
are assigning a logical name). The equivalence name can 
contain from 1 to 255 characters. If the equivalence name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") wherever you 
want a quotation mark to appear. 
Note that if you enclose an equivalence name string in 
quotation marks, uppercase and lowercase letters are 
retained as is. 

In 


The logical name. The logical name can contain from 1 to 
255 characters. 


If the logical name contains quotation marks, enclose _ the 
string in quotation marks and use two sets of quotation 
marks ("") wherever you want a quotation mark to appear. 


Note that if you enclose a logical name string in quotation 
marks, the case of the alphabetic characters is preserved. 


Syntax descriptions 
ASN en:=I1n:[/keywords(s) ] 
Makes a session logical name assignment for the terminal 


from which it was”) entered. However, when entered with 
keywords, this command can make user or system assignments. 


Keywords: 
/ CONCEALED 
Specifies that the equivalence name is a _ concealed 
device. Additionally, the / FINAL keyword is 
automatically applied by the system. 
/FINAL 


Specifies that the equivalence name string should not 
be translated iteratively; that is, the logical name 
translation should terminate with the current 
equivalence string. 

/GBL or /SYSTEM 


Makes a global (system-wide) logical assignment. A 
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global assignment is entered into the system-level 
translation table and it applies to all tasks and 
applications running in the system. 


/USER 


Makes a user (application-wide) logical assignment. A 
user assignment is entered into the user-level 
translation table and it applies to all tasks running 
for the current application. 


/SESSION 
Makes a session logical assignment. A session 
assignment 1s entered into the session-level 


translation table and it applies to all tasks and 
applications for the current logged in session. 


ASN =[1n:][{/keywords(s) ] 
When entered without parameters, deletes all session logical 


assignments for the terminal from which it is entered. When 
entered with a specific logical name assignment, deletes 


that specific assignment. When entered with keywords, 
deletes all of the logical name assignments of the specified 
type. 


Note that when you delete logical assignments with the ASN 
command, the command deletes assignments made by the DFL 
command as well. 


DIGITAL does not recommend deleting logical assignments in 
the SESSION or SYSTEM logical name tables. 


Keywords: 
/ CONCEALED 


Specifies that the logical name assignment to _ be 
deleted is a concealed device. 


/GBL or /SYSTEM 
(Privileged keyword) Deletes all global logical 
assignments or a specific global assignment if one is 
specified. 


/ SESSION 


Deletes all session logical name assignments or a 
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Specific session assignment if one was specified. 


/ USER 


Deletes all user logical assignments or a specific user 
assignment if one is specified. 


ASN [1ln:][/keyword(s) ] 


Displays the session logical assignments for the terminal 
from which it is entered (when entered without a keyword) or 
a specific logical name assignment if one is specified. If 
a logical name is specified the system displays all of its 
iterative translations. 


Keywords: 


/ALL 


Displays all user and session logical assignments of 
the terminal from which it is entered, and all 
system-wide logical assignments. 


/GBL or/SYSTEM 


Displays the system-wide logical name assignments or 
the assignment of a particular logical name in the 
system-wide table if one was specified. 


/USER 


Displays the user logical name assignments or_ the 
assignment of a particular logical name in the 
application-wide table if one was specified. 


/ SESSION 


Displays the session logical name assignments or _ the 
assignment of a particular logical name in the 
session-wide table if one was specified. 


ATL 


D.2.5 ATL 


ACTIVE TASK LIST (NP) 

The ACTIVE TASK LIST (ATL) command displays the name and status 
of all active tasks in the system or the status of a particular 
task. The display provides information useful in determining the 


exact status of each active task. The display contains the 
following information for each task: 


@® Task name 

@e Task control block physical address (octal) 

e Partition name 

@® Partition control block physical address (octal) 

@e Partition base and limit physical addresses (octal) 
e Task’s running priority and default priority 

e Tasks status flags 

e TI: terminal physical device-unit 

e nonbuffered and buffered I/O counts (decimal) 

e Task local event flags 


e Task registers and Processor Status Word 
(memory-resident tasks only) 


@e The name of the parent task (if one exists). 


e Task blocking count 


The display lists the tasks installed in primary pool and_ then 
those installed in secondary pool. The tasks in secondary pool 
are indicated by a plus sign (+). 


The display task status flags are from the Task Control Block 
(TCB) or the Partition Control Block (PCB). The ATL command 
displays the name of the bit if the bit is set to 1 at the time 
of the display. Bits set to 0 are not displayed. Flag names are 
three characters long and correspond to the last three characters 
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of the mnemonic defining the status bits. For example, AST 
represents the bit T2.AST and indicates that the task is 


processing an Asynchronous System Trap. Names prefixed by a 
minus sign (-) indicate that the bit represents the complement of 
the condition. For example -CHK indicates that the task cannot 


be checkpointed. 


If the task is not in memory (the OUT flag is displayed), the 
contents of the PC (program counter), the PSW (Processor Status 
Word), and the registers are not displayed. 


The following list provides a brief description of each task 
status flag: 


Status 
Flag 


ABO 
ACP 
AST 
BLK 
CAF 
CAL 
CHK 
CIP 
CKD 
CKP 
CKR 
CLI 
DSP 
DST 
-EXE 
FXD 
GFL 
-PMD 
OUT 
PRV 
RDN 
REM 
REX 
ROV 
RST 
SEF 
SLV 
SNC 
SPN 
SPNA 
oD 
STPA 
SWS 
WFR 
WFRA 
LDD 
MUT 
PRO 
PRVD 
XHR 


ATL 


Description 


Task is being aborted. 

Task is an Ancillary Control Processor (ACP). 
Task is processing an AST. 

Blocked externally by a CLI command 
Dynamic checkpoint allocation failure 
Checkpoint space allocated in task image 
Not checkpointable 

Blocked for checkpoint in progress 
Checkpoint disabled 

Checkpointed 

Checkpoint request pending 

Command Line Interpreter 

Task was built for user-mode I- and D-space 
ASTs disabled 

Not executing 

Fixed in memory 

Task has own group global event flags locked 
Suppress PMD on SST abort 

Out of memory 

Privileged 

I/O being run down 

Remove on exit 

Abort AST effected or in progress 

Resident overlays 

Restricted - used by layered software 
Stopped for event flag 

Slaved 

Task uses commons for synchronization 
Being suspended 

Suspended prior to AST 

Stopped 

Stopped prior to AST 

Reserved for software services 

In a wait-for state 

In a wait-for state prior to AST 

Task’s load device has been dismounted 
Task is a multiuser task 

Task is (or should be) a prototype task 
Task was privileged but has cleared T3.PRV 
Task has an external header 


gore ansaid AERA LTT LST LN 


Syntax 


ATL [taskname] 


taskname 


The name of a specific task to be displayed. 
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D.2.6 BLK 


BLOCK (NP,P) 


The BLOCK command blocks an installed task. It declares to’ the 
system that the specified task is not eligible to execute or 
compete for memory. Nonprivileged users can only block active 
tasks requested from the issuing terminal. Privileged users can 
block any task. 


However, the following tasks cannot be blocked: ACP tasks, CLI 
tasks, tasks that are being aborted, and tasks that are exiting. 


Blocking a task sets the block bit in the Task Control Block 
(TCB). When a task’s block bit is set, the task is ineligible to 
compete for system resources. To clear the block bit, issue the 
MCR UNBLOCK command, or, if the task is active, abort the task. 
(Unblocking or aborting a task are the only ways to cancel the 
BLOCK command. ) 


A blocked task has an effective priority of zero. If the task 
can be checkpointed, any task can checkpoint it. Once 
checkpointed, the blocked task is no longer eligible to compete 
for a space in memory. A blocked task that is subsequently 


aborted is automatically unblocked by the system. If the task 
had previously specified a requested exit AST, the task is 
unblocked and the AST is declared for it. 
Syntax 
BLK [taskname] [/TERM=TTnnn: ] 
taskname 
The name of the task to be blocked. If taskname is not 
specified, the command attempts to block the task requested 
from the issuing terminal (task TTnnn). 


/TERM=TTnnn: 


A privileged keyword that specifies that a task initiated 
from the specified terminal should be blocked. 


BRK 


D.2.7 BRK 


BREAKPOINT TO EXECUTIVE DEBUGGING TOOL (P) 


The BREAKPOINT TO EXECUTIVE DEBUGGING TOOL (BRK) command passes 
control to the Executive Debugging Tool (XDT) if XDT has been 
installed on the system. If XDT is not in the system the command 
has no effect. If successful, the BRK command halts all system 
activity. Proceeding from a breakpoint normally restores’ the 
system to the state that existed when the BRK command was issued. 


When XDT gains control, it prints the following message on the 
terminal connected to the printer port: | 


BE: mnnnnn XDT> 
This message confirms that XDT has control. All XDT commands are 
available for use in debugging the Executive or user-written 
drivers. To proceed with system operation, enter the P command. 
You must issue the BRK command from the console terminal (TT1:). 


Syntax 


BRK 


CAN 


D.2.8 CAN 


CANCEL (NP,P) 


The CANCEL command cancels time-based initiation requests for a 


task. These requests result from a RUNS directive or any of the 
time-synchronized variations of the RUN command that are _ placed 
into the clock queue. (Note that you must be privileged to use 


these forms of the RUN command. ) 


Only a privileged user can issue a CANCEL command for a task not 
initiated from the entering terminal. 


CANCEL does not effect execution of a currently active task. 
CANCEL removes only the time-based schedule requests still in the 
clock queue. 
Syntax 

CANCEL taskname 


where taskname is the name of the task. 


CBD 
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COMMON BLOCK DIRECTORY (NP) 


The COMMON BLOCK DIRECTORY (CBD) command displays information 
about all entries or a specific entry in the Common Block 
Directory. The Common Block Directory is a table of all named 
common regions and libraries installed in the system. 


The display contains the following information for each named 
common region: 


e® Common region name 
e Partition Control Block (PCB) address 
@e The number of tasks mapped to the common region 


e® Common region status bits. The following is a list of 
the status bits and their meanings: 


CAF Checkpoint allocation failure 
-CHK Cannot be checkpointed 

CKP Checkpoint in progress 

CKR Checkpoint request 

COM Library or common 

DEL Delete on last detach 

DRV Driver common 

FXD Fixed in memory 

Lio ‘Long 170 

LFR Last load failed 

NSF Cannot shuffle 

OUT Out of memory 

PER Parity error 

PIC Position independent 

NWB Common should not be written back 
RON Read-only common 


Usually , the status bits will indicate that the common 
region is either fixed in memory (FXD) or out of memory 
(OUT). 


An optional keyword (/TASKS) displays a list of all tasks 
attached to a specific common region and the number of times each 
task has mapped to the common region (mapping count). 


CBD 


Syntax 
CBD [common-region-name[/TASKS] ] 
common-region-name 
The name of a specific common region. 
Keyword: 
/TASKS 
Displays the names of each task attached to ae specific 


common region and the number of times the task has mapped to 
the region (mapping count). 


CLQ 
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CLOCK QUEUE (NP) 


The CLOCK QUEUE (CLQ) command displays on the entering terminal 
information about tasks currently in the clock queue. The 
information consists of the task names, the next time each task 
is to be run, and each task’s reschedule interval, if one was 
Specified. The system places a task in the clock queue if the 
task was activated by the RUNS directive or any of the 
time-synchronized variations of the RUN command. (Note that you 
must be a privileged user to use these forms of the RUN command. ) 


Syntax 


CLQUEUE 


DCL 


D.2.11 DCL 


DIGITAL COMMAND LANGUAGE (NP) 

The DIGITAL COMMAND LANGUAGE (DCL) command allows you to issue 
DCL commands while MCR is processing commands. Instead of MCR 
processing the command line, DCL processes it. See the Command 
Language Manual for descriptions of the DCL commands. 


Syntax 


DCL command-line 


DEB 


D.2.12 DEB 


DEBUG (NP,?P) 


The DEBUG command forces a task to trap to a debugging aid by 
setting the T-bit in the task’s Processor Status Word (PSW). You 
can debug a task that was built with the /DA switch or that was 
issued a SPECIFY SST VECTOR TABLE FOR DEBUGGING AID (SVDBS) 
directive. (Refer to the RSX-11m/M-PLUS and Micro/RSX Task 
Builder Manual. ) 


Nonprivileged users can debug any nonprivileged task that was 
initiated from their own terminals (TI:). Privileged users can 
debug any task. 


Tasks for which you might want to use the DEBUG command are those 
that are in an infinite loop or are waiting for an incorrect 
event flag. 


If you enter the DEBUG command, but no debugging aid was 
specified for the task, you will get the error message "Task does 
not contain a debugging aid." 


Syntax 
DEBUG [taskname] 
taskname 
The name of the task you want to debug. If you do not 


specify a task name, DEBUG looks for a task TTnn, which is 
the task currently running from your terminal. 


DEV 
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DEVICES (NP,P) 


The DEVICES COMMAND displays the symbolic names of all devices or 
all of a particular device type or the name of a specific device. 
The device names appear in one column; second and _ subsequent 
columns contain information about each device. 


Syntax 


DEVICES 
DEVICES dd: 
DEVICES ddnnn: 
DEVICES /LOG 


dd: 


The type of device for which you want the information to be 
displayed. This parameter must be a physical device name. 


ddnnn: 


The specific device for which you want the information to be 
displayed. This parameter may be either a physical device 
Or a pseudo device name. 


/ LOG 
Displays all logged-in terminals. 
On P/OS systems, when you specify a terminal or /LOG, the display 
includes the login and default uics, the date and time of login, 
the number of tasks currently active, and the last name of each 
logged-in user. 
Notes 
The following notes describe the information that can appear in 


the displays. 


@ MOUNTED indicates that the device is mounted. If a 
privileged user issues the command, the display includes 
the volume label. 


@® PUBLIC indicates that the device is set public. 


DEV 


NOWRITE indicates that the volume is software 
write-locked (write operations are not allowed on the 
volume). 


TYPE indicates the device type. 


MARKED FOR DISMOUNT indicates that a mountable device 
has been requested to be dismounted, but the dismount 
operation has not yet completed. 


OFFLINE indicates that, although the system tables 
contain entries for this device, the device was powered 
down at the time of boot. 


[ulc] LOGGED ON indicates that the user identified by 
[uic] (the protection UIC) has logged in on the 
terminal. 


LOADED indicates that a loadable device driver is 
currently loaded. 


UNLOADED indicates that a loadable device driver is not 
currently loaded. 


A device name in the second column is the device to 
which the corresponding device in the first column has 
been redirected. 


The lines in the display for a specific terminal list 
the characteristics that have been set for the terminal. 
The description of the SET command gives all of the 
available characteristics. 


DFL 
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DEFINE LOGICALS (NP,P) 


The DEFINE command assigns, deletes, or displays logical name 
assignments. A logical name assignment associates a user-chosen 
name with a physical device, a pseudo device, a logical device, a 
part of a Files-11 file specification, all of a Files-1i1 file 
specification, or another logical name. 


The system keeps’ logical names and their corresponding 
equivalence names grouped in pairs in the following logical name 
tables: 


@e The user logical name table contains logical name 
entries that are local to a particular application. 
When the application exits, the contents of the user 
logical name table is deleted. You use the /USER 
keyword to make an entry in the user logical name table. 


e The session logical name table contains logical name 
entries that are local to a particular user. By default 
the ASN and DFL commands place a logical name in the 
session logical name table. You can also use the 
/SESSION keyword to make an entry in the session logical 
name table. 


e The system logical name table contains entries that can 
be accessed by any task in the system. You use the 
/SYSTEM or /GBL keyword to make an entry in the system 
logical name table. 


When the system encounters a logical name, it searches’ the 
logical name tables in this order: user, session, and system. 
The system uses the first match it finds as the equivalence name 
for the logical name. When it finds an equivalence name, the 
system substitutes the equivalence name for the logical name in 
the file specification. This is called logical name translation. 


Logical name translation can be iterative. Iterative translation 
means that the system repeats the process of logical name 
translation until it resolves a logical name to its original 
device or file specification. 


You can control the translation of logical names by using the 
/FINAL keyword. 


DFL 


The system limits logical name translation to eight levels. If 
you define more than eight levels or if you create a circular 
definition of a logical name, an error will occur if you try to 
use the logical name iteratively. 


If you are ever in doubt about the equivalence name assigned to a 
logical name, you can use the ASSIGN command to display the 
current assignment by typing DFL and the logical name, then 
pressing the RETURN key. 


You can use logical names to define concealed devices. Concealed 
devices are used to associate a logical name with a device anda 
directory name. Subsequent uses of the logical name result in 
the device and directory being used as the Master File Directory 
(MFD) for all file operations. The following is an example of a 
concealed device. 


SDFL CD001:= _DW002:[CHARLES. ] /CONCEALED 
SPIP CD001:[USERFILES]/LI 


Directory CD1i:[USERFILES] 28-JUN-85 11:20 
EXAMPLE.DAT 4 27-JUN-85 17:21 


As a result of the DFL command and the invocation of the PIP 
utility task, the contents of the directory [CHARLES.USERFILES] 
on the device DW002: was displayed to the terminal issuing the 
commands. 


The logical name DWO0Q1: is another example of a concealed 
logical name. 


If the /CONCEALED keyword is specified the physical device name 
must be of the form ddnnn: and the logical device name of the 
form _ddnnn:[dirspec.] where dirspec is optional. 


Syntax 
The DEFINE command has three types of syntax. Following is a 


brief list of each, along with a description of the terms used 
and descriptions of optional keywords. 


DFL ln:=en: [/keyword(s) ] 'Makes logical assignments 
DFL =[1ln:][/keyword(s) ] 'Deletes logical assignments 
DFL (ln: ][{/keyword(s) ] {Displays logical assignments 


The terms shown in the DFL command formats have the following 
meanings: 


DFL 


In 
The logical name. The logical name can contain from 1 to 
255 characters. If the logical name contains quotation 
marks, enclose the string in quotation marks and use_ two 
sets of quotation marks ("") in the places where you want a 
quotation mark to appear. 
Note that if you enclose a logical name string in quotation 
marks the case of the alphabetic characters is preserved. 

en 


The equivalence name (the name or specification to which you 
are assigning a logical name). The equivalence name can 
contain from 1 to 255 characters. If the equivalence name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") in the places 
where you want a quotation mark to appear. 


Note that if you enclose an equivalence name string in 
quotation marks the case of the alphabetic characters is 
preserved. 
Syntax descriptions: 
DFL Iln:=en:[/keywords(s) ] 
Makes a session logical name assignment for the terminal 
from which it was’ entered. However, when entered with 
keywords, this command can make user or system assignments. 
Keywords: 
/ CONCEALED 
Specifies that the equivalence name is a_ concealed 
device. Additionally, the / FINAL keyword is 
automatically applied by the system. : 
/FINAL 
Specifies that the equivalence name string should not 
be translated iteratively; that is, the logical name 
translation should terminate with the current 
equivalence string. 


/GBL or /SYSTEM 


Makes a global (system-wide) logical assignment. A 
global assignment is entered into the system-level 
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translation table and it applies to all tasks and 
applications running in the system. 


/USER 


Makes a user (application-wide) logical assignment. A 
user assignment is entered into the user-level 
translation table and it applies to all tasks running 
for the current application. 


/SESSION 
Makes a session logical assignment. A session 
assignment is entered into the session-level 


translation table and it applies to all tasks and 
applications for the current logged in session. 


DFL =[ln:][/keywords(s) ] 


Deletes all session logical assignments for the terminal 
from which it 1s entered. (when entered without 
parameters). When entered with a specific logical name 
assignment, deletes that specific assignment. When entered 
with keywords, deletes all of the logical name assignments 
of the specified type. 


Note that when you delete logical assignments with the DFL 
command, the command deletes assignments made by the ASN 


command as well. 


DIGITAL does not recommend deleting logical assignments in 
the SESSION or SYSTEM logical name tables. 


Keywords: 
/CONCEALED 


Specifies that the logical name assignment to be 
deleted is a concealed device. 


/GBL or /SYSTEM 
(Privileged keyword) Deletes all global Logical 
assignments or a specific global assignment if one is 
specified. 

/SESSION 
Deletes all session logical name assignments or a 


Specific session assignment if one was specified. 
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DFL 


/USER 


Deletes all user logical assignments or a specific user 
assignment if one is specified. 


DFL [ln:][{/keyword(s) ] 


Displays the session logical assignments for the terminal 
from which it is entered (when entered without a keyword) or 
a specific logical name assignment if one is specified. If 
a logical name is specified the system displays all of its 
iterative translations. 


Keywords: 


/ALL 


Displays all user and session logical assignments of 
the terminal from which it is entered, and all 
system-wide logical assignments. 


/GBL or/SYSTEM 


Displays the system-wide logical name assignments or 
the assignment of a particular logical name in the 
system-wide table if one was specified. 


/USER 


Displays the user logical name assignments or _ the 
assignment of a particular logical name in the 
application-wide table if one was specified. 


/ SESSION 
Displays the session logical name assignments or _ the 


assignment of a particular logical name in _ the 
session-wide table if one was specified. 


DMO 
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DISMOUNT (NP) 

The DISMOUNT command requests the file system to mark a volume 
for dismount and releases its control blocks. Marking a volume 
for dismount prevents programs from opening additional files. on 
the volume. After all open files on the volume are closed, the 
Ancillary Control Processor (ACP) releases the control blocks and 
dismounts the volume. 


There may be a considerable delay between the time you issue _ the 
command and when the volume is actually dismounted. 


Syntax 
DMO ddnmnn:[["]Jlabel["] ] 
ddnnn: 


The device unit that holds the volume to be dismounted. 


label 
The Files-11 volume label may be up to 12 characters in 
length. It is used to verify that the proper volume is 
being dismounted. A volume label is optional (if the 


command omits a label, no volume check is performed). 


EXIT 
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EXIT (NP) 


The EXIT command exits the application and returns control of the 
system to the P/OS Menu Services. 


When the application exits, the following is performed: 


All tasks that are active at your terminal and that were 
not installed with the /REMOVE=NO keyword when you 
issued the EXIT command are aborted. If a task has 
requested an exit AST service routine by means of a 
SPECIFY REQUESTED EXIT AST (SREAS OR SREXS) directive, 
the task enters this service routine. The command 
allows a certain time interval to elapse, after which if 
the task has not exited, EXIT aborts the task normally 
(a second requested AST cannot be declared for a 
nonprivileged task). Active tasks at your terminal 
(both privileged and nonprivileged tasks) that were 
installed with the /REMOVE=NO keyword are not aborted. 


If the EXIT command is executed on the console terminal 
Cre) all tasks that were installed without the 
/REMOVE=NO keyword are removed from the system. 


The contents of the USER logical name table are deleted. 


FIX 
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FIX-IN-MEMORY (NP) 


The FIX command loads and locks a task into its partition. 
Subsequent requests for running the task are serviced more 
quickly because the task is resident in memory and does not have 
to be loaded from disk before it can run. 


Fixed tasks remain physically in memory even after they exit. 
Therefore, they do not have to be reloaded when a request is made 
to run them. (Note that it is not always practical to reexecute 
fixed tasks. To reexecute, the task must initialize all impure 
data and LUN asSignments at run time.) Only the REMOVE command 
can free the occupied memory partition. 


The following restrictions apply to fixing tasks: 


e cCheckpointable tasks should not be fixed because fixing 
a checkpointable task makes the task noncheckpointable. 


e Tasks whose names are in the form ...xxx and xxxSSs 
cannot be fixed because that copy of the task is never 
executed. (The task is a prototype task.) 


e Active tasks cannot be fixed. 
e A task must be installed before it can be fixed or the 


/FIX keyword can be used with the INSTALL command to 
install and FIX a task into its partition. 


Syntax 
FIX taskname[/keyword] 


taskname 


The variable taskname is the name of the installed task to 
be fixed in memory. 


/REG 


The /REG keyword fixes a region. 


FIX 


/ RON 


The /RON keyword fixes a common, read-only segment of a 
multiuser task. 


FMT 
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FORMAT (NP) 


The FORMAT command deletes all existing files, locates any bad 
blocks, and sets up a hard disk as a recognizable FILES-1i1 volume 
by its controller. Once you have formatted a disk, you can use 
the INITIALIZE command to initialize it. 


Normally, the P/OS installation procedure formats the system 
disk. However, to connect additional hard disks to a 
Professional, you must format each one with the FORMAT command. 


Syntax 
FMT ddnnn: [/[NO]CONFIRM] 


ddnnn: 


The device and unit that contains the volume _ to be 
formatted. 


/{NO]CONFIRM 


Specifies whether or not P/OS should check to see if the 
volume is already in FILES-11 format. If you do not specify 
/NOCONFIRM and the volume already contains the FILES-11 
structure, you are prompted to confirm the FORMAT request. 


The default is /CONFIRM. 


HEL 
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HELP (NP) 


The HELP command displays the contents of a general help file for 
your system. 


The default help file is LB:{1,2]MCR.HLP. 
Syntax 


HELP % [/OUT:filespec] [qualifier] [qualifier 2] [...qualifier 9] 
HELP [/keyword] [qualifier] [qualifier 2] [...qualifier 9] 


) 
xe) 


Displays the text contained in file HELP.HLP in the current 
directory on the default volume. 


qualifierl...qualifier9g 


The subject on which you would like help information to be 
displayed. 


Keywords (all mutually exclusive) 
Joc’ 


Specifies that the help text begins in the file 
LB:[1,2]DCL.HLP. 


/FIL: [filespec] 


Specifies any files where help text is located. If you do 
not give a complete file specification, the defaults are 
LB:[1,2]filename.HLP. If you only use /FIL:, the default 
help file is LB:({1,2]MCR.HLP. 


/LOC 
Displays the text contained in HELP.HLP in the default 
directory on the default volume. This keyword is equivalent 
to the HELP % command. 

/MCR 


Specifies that the help text begins in the file 
LB:{1,2]MCR.HLP. This is the default while executing MCR 
commands. 


HEL 


/OUT: filespec 


Saves the text of the help file (or files) in the specified 
file. If you do not use the /OUT keyword, HELP displays the 
files on your terminal. 


For information on the format of a help file see the file 
LB:[1,2]HELPF.HLP. Note that this file is only present if the 
PRO/Tool Kit or the PRO/MCR help files are installed. 


INI 


D.2.20 INI 


INITVOLUME (NP) 
The INITIALIZE VOLUME command produces a Files-11 volume. The 
command initializes the volume (destroys all existing files), 
writes a dummy bootstrap, a home block, and builds the directory 
structure. 
Syntax 

INITVOLUME ddnnn:["]volume-label["][/keyword(s) ] 


ddnnn: 


The device unit name and number of the volume to _ be 
initialized. 

["]Jvolume-label["] 
The volume label. This may be up to 12 characters in 
length. The label identifies the volume and must be 
specified. The volume label can contain the letters A 
through Z, and the digits 0 through 9. 

/keyword(s) 


The specifications for various characteristics you want’ the 
volume to have upon initialization. 


Keywords: 
f/ACSin 


Specifies the number of blocks to be allocated to _ the 
checkpoint file on the volume. The default is Q. 


/BAD 


Indicates that bad block processing is to be included in the 
volume initialization. Consequently, bad blocks’ on the 
volume will be marked as being currently in use and cannot 
be allocated to files. 


INI 


/{[NO]CONFIRM 


Specifies that the volume should not be checked to be 
already in Files-11 format. If the volume already contains 
the Files-11 structure you are prompted to confirm the 
INITIALIZE VOLUME request. The default is /CONFIRM. 


INS 
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INSTALL (NP) 


The INSTALL command makes a specific task executable by the 
system. An installed task is dormant (not active) until the 
Executive receives a request for the task to run. INSTALL 
accepts optional keywords that provide parameters that were not 
specified when the task was built or that override a previously 
specified parameter. 


When you install a task, the system creates a Task Control Block 
(TCB) for the task in a memory-resident table called the System 
Task Directory (STD). The task parameters contained in the fMTCB 
enable the system to run the task when requested to do so by an 
MCR command or a system directive. You cannot run a task until 
it has been installed. (Note that the RUN command has an option 
that automatically installs and removes a task before and after 
running it.) 


A TCB contains both the address of the load-device Unit Control 
Block (UCB) and the Logical Block number (LBN) of the task image 
file. Because task image files are contiguous, the Executive can 
load the task image in one transfer when an MCR command or system 
directive requests an installed task. (However, if the task 1s 
greater than 32K words, loading requires more than one transfer.) 
When you install a resident library, INSTALL makes an entry for 
the resident library in the Common Block Directory (CBD). The 
system loads the resident library when a task that uses it runs 
and removes the resident library when no task is attached to it. 
Syntax 

INSTALL [$]filespec[/keyword(s) ] 
filespec 

The file specification in the form: 


ddnnn:[dir-spec]filename.type;version 


The type defaults to TSK; standard defaults apply to _ the 
remaining fields. 


When you specify $ in the command line, ddnnn: defaults to 
LB: and [dir-spec] defaults to [ZZPRODCL]. 
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INS 


Keywords: 
/FIX 


Specifies that the task should be loaded and locked into its 
partition after the install process completes. 


/REMOVE=option 


Specifies whether the task should be removed from the system 
when the application exits. The default is /REMOVE=YES. 
(The task is removed when the application exits.) The task 
is not removed unless you issue the REMOVE command, 
specifying the taskname. If you specify /REMOVE=NO, the 
task is not removed when the application completes. 


/RON=option 


Specifies read/write access for a common region. The 
options are YES and NO. If you specify /RON=YES, the region 
is installed as read-only. If you specify /RON=NO, the 


region is installed with read-write access. 


The default is /RON=NO (the region is installed with 
read-write access). 


/TASK=taskname 
Specifies the name by which the system refers to the task. 


The default taskname is the name specified at task-build 
time, or the first six characters of the file name. 


/WB=option 


Specifies the file to which a read/write common will be 
checkpointed. The options are YES and NO. By default, a 
common is checkpointed to a system checkpoint file. 


If /WB=YES, the common is checkpointed to its original task 
image file; also, when the common is removed, it is written 
back to its original task image file. 


If /WB=NO, the common is checkpointed to a system checkpoint 
file, and it is not written back to the original task image 
file when it is removed. 


If a common is read-only, there is no need to checkpoint it. 
Thus INSTALL ignores the /WB switch if a common is installed 
with /RON=YES. 


The default is /WB=NO. 


INS 


LOA 
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LOAD (NP) 
The LOAD command reads a nonresident (loadable) device driver 
into memory and, if necessary, relocates the data base constructs 
and interrupt-vector linkages required to allow access to _ the 
device. 


The LOAD command allows loading of a device driver during 
development. In order to include the driver into the system from 
an application, a call to PROLOD must be performed. Refer to the 
Guide to Writing a P/OS Driver Manual. 


Syntax 
LOAD dd: 
dd: 
A 2-character ASCII loadable device driver name. The 


loadable driver and its symbol table file (.STB) must be 
located in LB:[ZZSYS]. 


LUN 
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LOGICAL UNIT NUMBERS (NP) 


The LUN command displays the static logical unit number’ (LUN) 
assignments for a specified task. (Static assignments are those 
recorded in the task’s disk image file.) The display consists of 
a list of physical device units in one column and their 
corresponding LUNs in an adjacent column. 


When the specified task is running, the display does not 
necessarily reflect the running task’s assignments. For example, 


an Executive directive issued from within the task (ASSIGN _ LUN) 
can alter the LUN assignments. 


Syntax 
LUNS taskname 
taskname 


Specifies the taskname whose static lun assignments are _ to 
be displayed. 


MOU 
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MOUNT (NP) 

The MOUNT command allows the files system software access to 
physical devices. For all volumes on these devices, MOUNT 
creates the file system control blocks that the Ancillary Control 
Processor (ACP) uses to support data access on the device. MOUNT 


also declares, provided an on-line access patch exists, that the 
volume is logically on line for access. 


The MOUNT command supports the following two types of devices: 
@e File-structured devices. Initialized disks are an 
example of a file-structured devices. 
@e Non-file-structured devices. Devices with an 


unformatted or nonstandard file structures are examples 
of non-file-structured devices. 


Syntax 
MOUNT ddnnn:["]Jlabel[{"][{/keyword] 


ddnnn: 


Device unit on which the volume is to be mounted. There 1s 
no default device unit; you must specify one. 


label 


The Files-11 volume label may be null or up to 12 characters 
in length. It is used to ensure that the correct volume is 


being mounted. 


/FOR 


Indicates a foreign (non-Files-11) volume. 


OPE 
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OPENREGISTER (P) 


The OPENREGISTER command allows examination and optional 
modification of a word in memory. To open a location within a 
task, the task must be fixed in memory. 


By default, OPEN displays a location and its contents in octal. 
Special control characters allow you to have the information 
displayed in ASCII, Radix-50, double byte, or decimal format. To 
specify a different format, type the desired control character 
followed by the ESC key (use <CRTL/3> on the console terminal 
TTL?) You can do multiple conversions for the same location on 
one line. The display remains on the same line until you open 
the next location. 


You use the same control characters to insert new values into a 
location in ASCII, Radix-50, double byte, or decimal format. In 
this case, type the desired control character followed by the new 
value and then press the RETURN key to insert the new value and 
open the next location. 
Syntax 
OPEN memory-address [+ or -n][{/keyword] 
memory-address /contents [control-character][value]line-terminator 
The first line is the OPEN command line. The second line is 
the general format in which OPEN displays the contents of 
the location. After that, you can display and change _ the 
contents in various formats. 
memory-address 
A 1 to 8 digit octal memory address (location). 


+ OY =f 


One or more optional octal numbers to be added to or 
subtracted from the memory address. 


/keyword 
One of the keywords defined later in this text. 


control-character 


OPE 


One or more optional special characters used to display 
values Or insert new values in octal, ASCII, single 
character ASCII, Radix-50, double-byte, or decimal format. 
The special characters and their related formats are: 


/ - octal (default mode) 


" - ASCII 

’ - single-character ASCII 
% - Radix-50 

\ - double-byte 

. - decimal 


line-terminator 


The line terminator directs the subsequent action of OPEN. Any 

value that is entered replaces the contents of the word whose 

address and current value are shown in the first part of the 
display line. The slash (/) is part of the display line. 


ESC 


ESC or ALTMODE: ESC (or ALTMODE) terminates acceptance 
of further input and is the only exit from the OPEN 
command. If used after a special control character, it 
converts the contents of a location from octal to the 
desired format. 


RET 
RETURN: the next sequential location is opened. If 
used after a special control character and new value 


sequence, it inserts the new value in the _ specified 
format into a location. 


“RET 


Circumflex (up-arrow on some terminals)/RETURN: the 
previous location is opened. 


*RET 

or @RET 
Asterisk/RETURN or at-sign/RETURN: the location 
pointed to by the contents of the opened location is 
opened. 

>RET 


Right-angle bracket/RETURN: the contents of the open 
location are treated as a branch instruction. The 
effective address of the branch is the next opened 
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OPE 


location. You cannot supply a value (modify the 
current open location) and close the location with a 
right-angle bracket/RETURN. 


Keywords: 
/DRV=dd: 


Accesses an address relative to the beginning of the 
partition that contains the loadable driver for’ the 
specified device. 


/KNL 
Accesses the first 32K of the Executive memory. 
/REG=region-name 


Accesses an address relative to the beginning of the 
specified region. 


/TASK=taskname 


Accesses an address relative to the specified task (the task 
partition). Note that the task must be fixed. 


After accepting the first input line, OPEN finds the memory 
location to be accessed by using either: 


® The keyword 


@e The specified address as the actual address 


When /DEV, /REG, and /TASK are used, the supplied memory address 
(a virtual address in the partition) is modified by + or -n. The 
absolute address thus formed is used to display the second line 
Shown in the command format. In particular, the virtual address 
(task, partition, or kernel) and its contents are displayed. You 
may then enter an optional replacement value, followed by a line 
terminator. 


An attempt to specify an illegal location or access beyond _ the 
limits of the partition causes an error message. You are limited 
to the specified memory region (TASK or REG). However, if you do 
not use a keyword in the command line, OPEN can access any 
address of physical memory. 


D.2.26 PAR 


PAR 


PARTITION DEFINITIONS (NP) 


The PARTITION DEFINITIONS (PAR) 
each memory partition in the system. The display consists of six 


columns that specify: 


1. Partition name 


command displays a description of 


2. Address of Partition Control Block (PCB) 


3. Starting address of partition (octal) 


4. Size of partition (octal) 


5. Partition type 


MAIN 
TASK 
DRIVER 
RO COM 
RW COM 
DEVICE 


Main partition 


Partition 
Partition 
Partition 
Partition 
Partition 


contains a task 

contains a device driver 
is a read-only common 

is a read/write common 

1s a common and is mapped 


to the I/O page 
SEC POOL Partition is in secondary pool 


6. Description of partition occupant in the form: 

[ taskname ] An inactive resident task 

< taskname > An active task 

( dd: ) The specific device driver 

+ XXXX + The name of the first installed 
task that is associated with an 
unnamed common, usually the 
read-only segment of a multiuser 
task 

Lx KK. The name of the common 


Syntax 


PARTITIONS 


REA 
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REASSIGN (P) 
The REASSIGN command reassigns a task’s logical unit numbers 
(LUNs) from one physical device unit to another. The 
reassignments affect only the static assignments recorded in the 
task’s image file on disk. 
The command does not affect a memory-resident task. Hence, 
REASSIGN has no effect on the assignments of a currently 
executing task, or the assignments of a task that is fixed in 
memory. 
Syntax 
REASSIGN taskname lun ddnnn: 

taskname 

The name of the task. 
lun 

The logical unit number of the task. 


ddnnn: 


The new device unit, which can be either a physical or a 
pseudo device. 


REM 


D.2.28 REM 


REMOVE (NP) 
The REMOVE command deletes an entry (a task name) from the System 
Task Directory (STD) and thereby removes a task from the system. 
The removal of a task from the system makes the task 
unrecognizable to the system. This action is the complement of 
INSTALL. All that remains of the task in the system is the task 
image file. 


Syntax 
REMOVE taskname [/REG] 
taskname 
The name of the task to be removed. 
/REG 


Specifies that the taskname to be removed iS a= region 
installed in the Common Block Directory (CBD). 


RES 
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RESUME (NP,P) 


The RESUME command continues execution of a previously suspended 
task. 


A nonprivileged user can issue the RESUME command only for’ tasks 
initiated from the issuing terminal. A privileged user can 
direct the RESUME command to any suspended task. 
Syntax 
RESUME taskname[/TERM=ttnnn: ] 
taskname 
The name of the task to be resumed. If you omit the task 
name, the command attempts to resume the task TTnn (where nn 
is the octal unit number of the issuing terminal). 


/TERM=ttnnn: 


A privileged keyword that resumes a task initiated from the 
specified terminal. 


Note: 


A task cannot suspend any task other than itself. The 
RESUME command allows such a suspended task to proceed. 


RUN 
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RUN (NP,P) 


The RUN command initiates the execution of a task. The command 
can cause a task to be: 


@e Run immediately (NP) 
@e Run at a time increment from now (P) 


@e Run at a time increment from clock unit synchronization 
(P) 


@® Run at an absolute time of day (P) 


@e Installed, immediately run, and removed on exit (NP) 


All of these options, except install-run-remove, are available 
with or without rescheduling. 


You cannot run a task using the ...xxx form of the taskname, that 
is, you cannot specify RUN ...xxx. The ...xxx (and xxx$$$) form 
is used for the prototype copy of the task, which is never 
executed. 


Syntax 


RUN has five syntax variations. 


1. Run immediately (nonprivileged option). 
RUN taskname 


RUN looks for the task image file in the System Task 
Directory (STD) to see if the task is already installed. 
If RUN finds the task, it proceeds to run it. If RUN 
does not find the task, it looks for the file in the 
current directory on the current default device (SY:) to 
which the terminal requesting the task is set, and then 
installs and runs the task. 


RUN waits for the task to emit status before accepting 
another command. 


as 


RUN 


Run at a time increment from now (privileged option) 
RUN taskname dtime [/RSI=magu] 
taskname 


A 1 to 6 character task name. 


dtime 


The time at which the task will be initiated 


time units from the command issuance. This time 
parameter consists of two fields: a magnitude 
field and aunits field. The parameter is in the 


form magu where mag is the magnitude and u 1s 
of the following time units: TT, S, M, or H. 


The magnitude is the number of units to be clocked. 
It cannot exceed 24 hours in the specified unit and 


is decimal by default. 


The unit fields are T, S, M, and H: 


T 
Ticks. A tick is a clock interrupt. T can be 
any positive value from 0 to a maximum length 
of 15 bits. 
S 
Seconds. S can be any positive value from 
to a maximum of 15 bits. 
M 
Minutes. M can be any positive value from 
to 1440(decimal). 
H 


Hours. H can be any positive value from 0 
24(decimal). 


/RSI 


The reschedule interval. The RSI is the same 


for dtime. The reschedule interval specifies how 
often the task is to be rerun. Thus, each time the 
specified interval of time elapses, an initiation 


request is made for the specified task. 
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If the magnitude is equal to 0 (zero), then the 
reschedule interval is set to 1. Specifying 
/RSI=0H is the same as specifying /RSI=1H. 


Note that the CANCEL and the REMOVE commands negate 
the effect of this keyword. 


The default is no rescheduling. 
Run at a time increment from clock unit synchronization 
(privileged option). 
The system determines the task start-time by waiting for 
the first specified time unit (hour, minute, second, 
tick) to increment and then waiting for the specified 
time to elapse. 

RUN taskname sync [dtime][{/RSI=magu] 


taskname 


A 1 to 6 character task name. 


sync 
H - Synchronize on the next hour 
M - Synchronize on the next minute 
S - Synchronize on the next second 
T - Synchronize on the next tick 

dtime 
See Syntax 2. If present, dtime is added to the 
synchronization unit to produce the actual run time 
for running the task. 

/RSI 


See Syntax 2. 


Run at an absolute time of day (privileged option). 
RUN taskname atime [/RSI=magu] 
taskname 


A ito 6 character task name. 


RUN 


atime 


/RSI 


Absolute time of day at which to initiate this 
task. 


Input format is hh:mm:ss. 
hh - Hours (decimal assumed) 


mm - Minutes (decimal assumed) 
ss - Seconds (decimal assumed) 


See Syntax 2. 


Install, run immediately, and remove on exit 


RUN [$]filename [/keyword(s) ] 


S 
When you specify $ in the command line, ddnnn: 
defaults to LB: and [dir-spec] defaults to 
[ZZPRODCL]. 

Filename 
The name of the task image file to run. 

Keywords: 


/CMD="command-line" 


Passes the specified command line to the task _ for 
processing. For some tasks the command line must 
begin with the task’s acronym and it must be valid 
for the task (for example, if the task being run is 
PMA, "command-line" must be ae valid MACRO-11 
command line) or a syntax error will occur. When 
the task has finished executing the command line, 
the task is removed. 


/TASK=taskname 


Specifies the name the task will use while it is 
running. This name is a temporary assignment only. 
If taskname is not found in the STD, MCR names it 
TTnnn by default, where nnn is the unit number of 
the requesting terminal. 


SET 
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SET (NP,P) 


The SET command dynamically changes characteristics of and 
displays information about the system, tasks, and devices. 


Nonprivileged users can change the characteristics of their own 
terminals (the pseudo device TI:). Privileged users can change 
the characteristics of any device and also of any task and of the 


system. All users can display information about any device or 
task or about the system. 


Nonprivileged options: 
e Establish characteristics for the issuing terminal 
CTE 


@e Set the default device and directory for the issuing 
terminal. 


® Display status (determined by the keyword specified) of 
all terminals and other devices. 


e Display statistics about system dynamic memory. 


e Establish the default file protection for all files 
created during the current logged in session. 


Privileged options: 
@e Establish characteristics for any device in the system. 


Improper use of the SET command from a privileged terminal can 
result ina situation in which privileged user input will not be 


accepted. 
Syntax 
SET /keyword=values 
Only one keyword per command line is permitted. You can prefix 


most keywords with NO to negate or disable the function of the 
keyword. Exceptions are noted in the following section. 


SET 


Keywords: 


/(NO]ANSI[=TTnnn: ] 
/(NOJAVO[=TTnnn: ] 
/(NO]BLKMOD[=TTnnn: ] 
/(NO]BRO[=TTnnn: ] 
/BUF=ddnnn: [size] 
/{NOJCRT[=TTnnn: ] 
/{NO]DEC[=TTnnn: ] 
/DEF[=[({ddnnn: ][[directory]]] 
/(NO]DPRO[=protection-codes ] 
/(NOJEBC[=TTnnn: ] 
/(NOJECHO[=TTnnn: ] 
/(NOJEDIT[(=TTnnn: ] 
/{NO]JESCSEQ[=TTnnn: ] 
/{NO]FDX[=TTnnn: ] 
/(NO]FORMFEED[=TTnnn: ] 
/HPILL=TTnnn: [value] 
/(NO]HHT[=TTnnn: ] 
/{NO]HOLD[=TTnnn: ] 
/LINES=TTnnn: [value] 
/{NO]LOWER[=TTnnn: ] 
/PAR=pname 

/ POOL 
/(NO]PRIV[{=TTnnn: ] 
/(NO]REGIS 
/(NO]RPA[=TTnnn: ] 
/SECPOL 
/{(NO]SLAVE[=TTnnn: ] 
/(NO]SOFT[=TTnnn: J 
/(NO]SPEED=TTnnn: [RECV: XMIT] 
/TERM 
/(NO]TYPEAHEAD([=TTnnn: ] 
/(NO]JVFILL[=TTnnn: ] 
/([NO]WRAP[=TTnnn: ] 


Keywords: 
/ANSI[=ttnnn: ] 


Informs the system that the specified terminal supports ANSI 
standard escape sequences. 


When you omit =ttnnn:, the system displays all of the 
terminals that support the ANSI standard escape sequences. 


/NOANSI[=ttnnn: ] 


Informs the system that the specified terminal does not 
Support ANSI standard escape sequences. 


SET 


When you omit =ttnnn:, the system displays all of the 
terminals that do not support the ANSI standard escape 
sequences. 

/AVO[=ttnnn: ] 


Specifies that a vT100-series terminal has the advanced 


video option. This option enables the terminal to blink, 
bold, and flash parts of the screen, and to set the screen 
at 132(decimal) columns. If the word SET-UP blinks in 


set-up mode, the terminal has the advanced video option. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the advanced video option. 


/NOAVO[=ttnnn: ] 


Disables the advanced video option for’ the specified 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that do not have the advanced video option. 


/BLKMOD[=ttnnns: ] 


Enables local editing and block-mode transmission for the 
specified terminal. 


If you omit =ttnnn:, the system displays all of the 
terminals that have the block-mode option enabled. 


/NOBLKMOD[=ttnnn: ] 


Disables local editing and block-mode transmission for the. 
specified terminal. 


If you omit =ttnnn:, the system displays all of the 

terminals that have the block-mode option disabled. 
/BRO[=ttnnn: ] 

Enables the broadcast option for the specified terminal. 


If you omit =ttnnn:, the system displays all of the 
terminals that can receive messages. 


SET 


/NOBRO[=ttnnn: ] 
Disables the broadcast option for the specified terminal. 


If you omit -=ttnnn:, the system displays all of the 
terminals that cannot receive messages. 


/BUF=ddnnn: [size] 


sets or displays the default buffer size of the specified 
device. A nonprivileged user can display the buffer size of 
any device but can only set the buffer size of TI:. A 
privileged user can set the buffer size for any device. 


The specified size must be at least 15(decimal) and less 
than or equal to 255(decimal). 


If you omit size, the system displays the buffer size of the 
specified device. 


/CRT[=ttnnn: ] 


Defines the specified terminal as a Cathode Ray Tube (CRT) 
terminal and enables the backwards deletion option. 
Pressing the rubout or delete key moves the printing 
position one space to the left and erases any character 
displayed in that position. 


A nonprivileged user can display all terminals defined as 
CRTs but can only define TI: as a CRT. A privileged user 
can define any terminal as a CRT. 


If you omit =ttnnn:, the system displays all of the 
terminals that are defined as CRTs. 


/NOCRT[=ttnnn: ] 


Deletes the CRT status of the specified terminal and 
disables the backwards deletion option. 


A nonprivileged user can display all the terminals not 
defined as CRTs but can only delete CRT status for TI:. A 
privileged user can delete CRT status for any terminal. 

If you omit =ttnnn:, the system displays all of the 
terminals that are not defined as CRTs. 


/DEC[=ttnnn: ] 
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SET 


Indicates that the specified terminal is upward-compatible 
with the vT100-series of terminals. 


If you omit -=ttnnn:, the system displays all of the 
terminals that are upward-compatible. 


/NODEC[=ttnnn: ] 


Indicates that the Specified terminal is not 
upward-compatible with the vT100-series of terminals. 


If you omit -=ttnnn:, the system displays all of the 
terminals that are not upward-compatible. 


/DEF[(=ddnnn:[[directory] ] 


This command changes your default location in the system to 
the device and directory that you specify. The keyword 
establishes your default device or directory or both. When 
you do not explicitly specify a device or a directory in a 
file specification or command, the system supplies’ these 
defaults. 


The protection codes for the directory and its files control 
your activity in the directory. If you are a nonprivileged 
user, you have the directory and files access rights of the 
world category and, depending on your UIC, the group 
category. If you are a privileged user, you have the access 
rights of the system category. If your UIC matches the 
directory owner’s, you, of course, have the privileges of 
the owner category. 


You use the parameter ddnnn: to specify the name and unit 
number of the device. The device must be be a Files-11 
device. The device name can be a logical name, such as SY:. 
When you change your default device, the system generates an 
equivalent assignment of the logical name sy000: and 
assigns it to the device that you named. 


The directory parameter specifies the name of the directory 
that you want to be your default directory. 


When you omit =ddnnn: and directory, the system displays 

your current defaults. Note that even if you specify a 

logical name for the device, the system displays the name of 

the actual physical or concealed device. 
/DPRO=[ RWED, RWED, RWED, RWED ] 

Establishes your personal default protection code for all of 


the files you create after you issue this command. A 
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SET 


protection code specifies the type of access to your files 
that you want other users to have. The system recognizes 
four classes of users. The position of the user classes in 
the protection code string is fixed in this order: 
[SYSTEM, OWNER, GROUP, WORLD]. The location in the _ string 
defines which user class you are specifying. 


Also, the system recognizes four types of access for file 
protection purposes: 


- Read access 
Write access 
- Extend access 
- Delete access 


Um = wD 


You specify protection codes in the following ways: 


@ Enter the types of access that you want to allow each 
user class. The absence of a type denies that type of 
access to the user class. 


@® Enter commas to separate the entries for each user 
class. 


@ Enter a comma instead of any access types if you want to 
deny all types of access to a user class. The comma 
tells the system which user class is to be denied 
access. You must have some entry for each of the one of 
the four user classes, but you cannot enter a comma for 
every class (/DPRO=[,,,]). If you do, you will receive 
an error message. 


@® Enter the asterisk wildcard (*) instead of access types 
if you want to retain the current default access code 
for a user class. 


@ Enter the /DPRO keyword only (without specifying any 
codes) if you want to see a display of your current 
default file protection code. 


The /DPRO keyword establishes a default file protection for 
your current session at the terminal. If you want to enter 
a default protection code for all your future sessions at 
the terminal, use the Environment Services option on the 
P/OS Main Menu. 


/NODPRO 


Directs the system to create files using the default volume 
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SET 


protection rather than a personal default file protection 


Specified by the user. 
The default volume protection on P/OS is: 
[RWED,RWED, RWED, RWED ] 


/EBC[=ttnnn: ] 


Enables the eight-bit character option. The terminal driver 
passes all eight bits of the input characters’ to the 


Specified terminal. 


A nonprivileged user can display all terminals that have the 
option enabled but can only enable the EBC option for TI:. 


A privileged user can enable the EBC option for 
terminal. 


When you omit =ttnnn:, the system displays all of 
terminals that have the EBC option enabled. 


/NOEBC[=ttnnn: ] 


any 


the 


Disables the eight-bit character option. Before passing the 
input characters to the device, the terminal driver clears 


the eighth bit. 


A nonprivileged user can display all terminals that have the 
option disabled but can only disable the EBC option for TI:. 


A privileged user can disable the EBC option for 
terminal. 


When you omit =ttnnn:, the system displays all of 
terminals that have the EBC option disabled. 


/ECHO[=ttnnn: } 


any 


the 


Instructs the terminal driver to display each character 


typed on a specified terminal. 


A nonprivileged user can display typed characters on 


all 


terminals that have the ECHO option enabled but can only 


enable the echo option for TI:. A privileged user 
enable the echo option for any terminal. 


When you omit =ttnnn:, the system displays all of 
terminals that have the echo option enabled. 


/NOECHO[=ttnnn: ] 


Instructs the terminal driver to inhibit the display of 
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Can 


the 


all 


SET 


input characters typed on a specified terminal. 


A nonprivileged user can display all terminals that do not 
echo typed characters but can only disable the echo option 
for TI:. A privileged user can disable the echo option for 
any terminal. 


/EDIT([=ttnnn: ] 


Indicates that the terminal can perform ANSI-defined 
advanced editing functions. The Professional is an example 
of such a terminal. 


A nonprivileged user can display all terminals that have the 
option enabled but can only enable the edit option for TI:. 
A privileged user can enable the edit option for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the edit option enabled. 


/NOEDIT[([=ttnnn: ] 


Indicates that the specified terminal cannot perform 
ANSI-defined advanced editing functions. 


A nonprivileged user can display all terminals that do not 
have the option disabled but can disable the edit option for 
TI:. A privileged user can disable the edit option for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the edit option disabled. 


/JECSSEQ([=ttnnn: ] 


Enables the recognition of escape sequences from the 
specified terminal. The terminal driver treats the ESC 
character as the beginning of an eScape sequence rather than 
as aline terminator. See the P/OS System Reference Manual 
for further information about escape sequences. 


A nonprivileged user can display all terminals that can send 
and receive escape sequences but can only enable escape 
sequence recognition for TI:. A privileged user can enable 
escape sequence recognition for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that can send and receive escape sequences. 


/NOECSSEQ[=ttnnn: J 


SET 


Disables the recognition of escape sequences from the 
specified terminal. 


A nonprivileged user can display all terminals that do not 
recognize escape sequences but can only disable the option 
for TI:. A privileged user can disable escape sequence 
recognition for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have escape sequences recognition disabled. 


/FDX[=ttnnns: ] 


Instructs the terminal driver to accept input from _ the 
specified terminal while simultaneously outputting to it. 


A nonprivileged user can display all the full-duplex 


terminals but can only enable the option for TI:. A 
privileged user can enable the full-duplex option for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
full-duplex terminals. 


/NOFDX[=ttnnn: ] 


Disables the full-duplex option; the terminal driver does 
not Simultaneously process input and output from _ the 
specified terminal. 


A nonprivileged user can display all terminals that have the 
full-duplex option disabled but can only disable the option 
for TI:. A privileged user can disable the full-duplex 
option for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the full-duplex option disabled. 


/FORMFEED[=ttnnn: ] 


Indicates that the specified terminal has a hardware 
formfeed. 


A nonprivileged user can display all terminals that have a 
hardware form feed but can only declare it for TI:. A 
privileged user can declare it for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have a hardware form feed. 


/NOFORMFEED[=ttnnn: ] 


SET 
Indicates that the specified terminal will not have a 
hardware form feed. 


A nonprivileged user can display all terminals that do not 
have a hardware form feed, but can only specify the option 


for TI:. A privileged user can specify the option for any 
terminal. 
When you omit =ttnnn:, the system displays all of the 


terminals that do not have a hardware form feed. 


/HFILL=ttnnn: [value ] 


Specifies the number of fill characters (value) that the 
terminal driver places after a carriage return when 
outputting to the terminal. The range for the value is 0 to 


A nonprivileged user can display the number of sa os 
characters for any terminal but can only change the value 
for TI:. A privileged user can specify the number of fill 
Characters for any terminal. 


When you omit value, the system displays the fill character 
value for the specified terminal. 


/HHT[=ttnnn: ] 


Indicates to the terminal driver that the specified terminal 
has a hardware horizontal tab. 


A nonprivileged user can display all terminals that have a 
hardware horizontal tab but can only declare the option for 


TI:. A privileged user can declare the option for any 
terminal. 
When you omit =ttnnn:, the system displays all of the 


terminals that have a hardware horizontal tab. 


/NOHHT[=ttnnn: ] 


Indicates to the terminal driver that the specified terminal 
does not has a hardware horizontal tab. 


A nonprivileged user can display all terminals that do not 
have a hardware horizontal tab but can only declare the 
option for TI:. A privileged user can declare the option 
for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that do not have a hardware horizontal tab. 
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SET 


/HOLD[=ttnnn: ] 


Enables hold-screen mode at the specified CRT terminal. 
When hold screen mode is’ enabled, the terminal displays 
output one screenful at a time. The screenful of output 
remains on the screen until you press the SCROLL key while 


pressing the SHIFT key. The terminal then refills 


the 


screen. You can also advance the screen one line at a time 


by typing the SCROLL key. 


Hold-screen mode is useful while copying files to terminals 


that normally transmit at high baud rates (9600, 


example). Note, however, that hold-screen mode may not 


for 
be 


appropriate for use with certain types of programs (editors 
or terminals using different speeds for input and output, 


for example). 


A nonprivileged user can display all terminals currently 


in 


hold-screen mode but can only place TI: in hold-screen 


mode. A privileged user can place any terminal 
hold-screen mode. 


When you omit =ttnnn:, the system displays all of 
terminals that are currently in hold-screen mode. 


/NOHOLD[=ttnnn: ] 


ee) 


the 


Disables the hold-screen mode at the specified CRT terminal. 


A nonprivileged user can display all terminals not 
hold-screen mode but can only disable the option for TI: 


privileged user can disable hold-screen mode _ for 
terminal. 


When you omit =ttnnn:, the system displays all of 
terminals that have hold-screen mode disabled. 


/LINES=ttnnn: [value] 


Establishes the number of lines per page (value) for 


terminal. The range for value is 1 to 255(decimal). 
specify a decimal value, place a period (.) after 
number. 


A nonprivileged user can display the number of lines 


page for any terminal but can only specify the number 


TI:. A privileged user can specify the number of lines 
page for any terminal. 


/LOWER[=ttnnn: ] 


in 
A 
any 


the 


the 
TO 
the 


per 
for 
per 


SET 


Specifies that lowercase characters on a terminal or line 
printer are not to be converted to uppercase when they are 
received from the device driver. Note that this keyword 
only affects input from a terminal, not output to a 
terminal. 


A nonprivileged user can display all devices that do not 
convert lowercase characters to uppercase but can only 
specify the option for TI:. A privileged user can specify 
the option for any terminal or line printer. 


When you omit =ttnnn:, the system displays all the devices 
for which lowercase characters are not converted to 
uppercase. 


/NOLOWER[=ttnnn: ] 


Resets the characteristics for the terminal or line printer. 
For terminals, lowercase characters received in input are 
automatically converted to uppercase and echoed as 
uppercase. The keyword has no effect on characters output 
to the terminal. For line printers, lowercase characters 
output to the device are printed as uppercase. 


A nonprivileged user can display all the devices’ that 
perform this conversion but can only specify the option for 
TI:. A privileged user can specify the option for any 
terminal or line printer. 


When you omit =ttnnn:, the system displays all the devices 
for which conversion to uppercase is specified. 


/PAR=pname 


Displays an existing partition’s boundaries. 
pname 


The 1 to 6 character alphanumeric partition name. 


/ POOL 


Displays the size of the dynamic storage region in the 
format: 


POOL=top:max.:total. 
top 
The first location for user partitions (displayed in 


bytes with two trailing zeros suppressed). 
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SET 


max. 
The longest free block 
total. 
The total pool space 
/PRIV[=ttnnn: ] 
Establishes the specified terminal as 


A nonprivileged user can only display 


privileged. A privileged user can 
privileged. 
When you omit =ttnnn, the system 


privileged terminals. 
/NOPRIV[=ttnnn: ] 
Establishes the specified terminal to 


user can only display 
A privileged user can 


A nonprivileged 
nonprivileged. 


nonprivileged. 

When you omit -=ttnnn, the system 

nonprivileged terminals. 
/REGIS[=ttnnn: ] 

Indicates that the specified terminal 

graphics character. set. The 

such terminals. 

When you omit =ttnnn:, the system 


terminals that 
/NOREGIS[=ttnnn: ] 


the specified terminal 
character set. 


Indicates that 
ReGis graphics 


When you omit =ttnnn:, the system 
terminals that 
Set. 


/RPA[=ttnnns ] 


Enables the read-pass-all option of 
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(displayed in words). 


(displayed in words). 


a privileged terminal. 


the terminals that are 
set any terminal to be 


displays all of the 


be nonprivileged. 


the terminals that are 
set any terminal to be 


displays all of the 


Supports the ReGis 


VT125 and the vVT240 are two 


Support the ReGis graphics character set. 


displays all of the 
does not support the 
displays all of the 


do not support the ReGis graphics character 


the terminal driver. 


SET 


The terminal driver passes all input characters (including 
Special function characters such as CTRL/C) to the driver 
input buffer. 


A nonprivileged user can display all terminals that have the 
option enabled, but can only display the read-pass-all 
option for TI:, A_ privileged user can enable the 
read-pass-all option for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the read-pass-all option enabled. 


/NORPA[=ttnnn: ] 
Disables the read-pass-all option of the terminal driver. 
The terminal driver does not pass special function input 
characters (such as CTRL/C) from the terminal to the driver 
input buffer. 
A nonprivileged user can display all terminals that have the 
option disabled but can only disable the read-pass-all 
option for TI:, A privileged user can disable the 
read-pass-all option for any terminal. 
When you omit =ttnnn:, the system displays all of the 
terminals that do not pass special function characters to 
the terminal driver input buffer. 


/SECPOL 


Displays secondary pool use on the system. The display is 
in the following format: 


SECPOL=secfr:secsiz:pctfr 
secfr 


The number of free blocks in secondary pool in units of 
32(decimal)-word blocks. 


secsiz 


The size of secondary pool in units of 32(decimal)-word 
DrOecks:. 


petfr 
The percentage of free blocks in secondary pool. 


/ SLAVE 


SET 


Establishes the specified terminal as one that can enter 
data only if it is solicited from a task by READ QIOS. 
Thus, the specified terminal always rejects unsolicited 
input (other than CTRL/O, CTRL/Q, and CTRL/S). 


A nonprivileged user can display all slave terminals but can 
only establish TI as a slave terminal. A privileged user 
can establish any terminal as a slave terminal. 


When you omit =ttnnn:, the system displays all terminals 
that are currently classified as slaves. 


/NOSLAVE 
Removes slave status from a specified terminal. 


A nonprivileged user can only display nonslave terminals. A 
privileged user can set any slave terminal to be noslave. 


When you omit =ttnnn:, the system displays all of the 
nonslave terminals. 


/SOFT[=ttnnn: ] 


Indicates that the specified terminal can accept 
software-defined character sets. The VY20U0=series of 
terminals can accept these character sets. 


A nonprivileged user can display all terminals which have 
the soft option enabled but can only enable the option for 
TI: A privileged user can enable the soft option for any 
terminal. 


When you omit =ttnnn:, the system displays all of terminals 
which have the soft option enabled. 


/NOSOFT[=ttnnn: ] 


Indicates that the specified terminal cannot accept 
software-defined character sets. 


A nonprivileged user can display all terminals which have 
the soft option disabled but can only disable the option for 
TI: A privileged user can disable the soft option for any 
terminal. 


When you omit =ttnnn:, the system displays all terminals 
which have the soft option disabled. 


/SPEED=ttnnn:[recv:xmit ] 


SET 


Establishes the receive and transmit baud rates for 
terminals attached to the system through the printer port or 
a QUAD Serial Line Unit (SLU). The recv argument is_ the 
baud rate at which characters are input to the computer from 
the terminal. The xmit argument is the baud rate at which 
Characters are output to the terminal from the computer. If 
you do not specify either argument, the system displays’ the 
current settings. 


A nonprivileged user can display the speed settings for any 
terminal, but can set the speed only for TI:. A privileged 
user can set the speed for any terminal (except TT1:). 


Valid baud rates are 50, 75, 110, 134, 150, 300, 600, 1200, 
1800, 2000, 2400, 3600, 4800, 7200, 9600, and 19200. 


/TERM=ttnnn: [value] 


Establishes the terminal type (value) for the specified terminal. 
Supported standard terminal types are: 


ASR33 LA30S LAi20 VTO5B VT101 VIZXx 


ASR35 LA34 LAI80S vtT50 VT102 LA2xx 
KSR33 LA36 LA210 VI5Z VTLOS LNO3 
LA12 LA38 LOPO2 VT55 VT125 

LA30P LA5O LQOPO3 VT6l VEL sd 

LA75 LA100 PC3xx VT100 VT132Z 


A nonprivileged user can display the terminal type for any 
terminal but can only establish the terminal type for TI:. A 
privileged user can establish the terminal type for any terminal. 


When you omit the value parameter, the system displays the 
terminal type for the specified terminal. 


MCR also accepts an alternative form of the command. You can 
specify the terminal type and equate it to the desired terminal. 
This automatically associates certain characteristics of the 
particular terminal type with the specified terminal. (See the 
P/OS System Reference Manual Lor a list of implicit 
characteristics for each terminal type.) The command is in the 
format: 


SET /term-type=ttnnn: 


where term-type is one of the standard terminal types. Note that 
the terminal types are mutually exclusive. 


You can also use an alternative command form to display all of 
the terminals that are not a specified type. The format is as 
follows: 


SET 


SET /NOterm-type 


Note that you cannot negate a terminal type for a terminal. You 
can only display the terminals that are not a specific type. 
Negating terminal type returns a syntax error since the terminal 
would be an indeterminate type. 


/TYPEAHEAD[=ttnnn: ] 


Instructs the terminal driver to store input characters ina 
buffer before passing the characters to a requesting task. 
Thus, characters input between requests are not lost. 


If /TYPEAHEAD is enabled for a terminal, the typeahead 
buffer size is set to 36 characters. 


A nonprivileged user can display all terminals that have the 
typeahead option enabled but can only enable the option for 
dn A privileged user can enable typeahead for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have typeahead enabled. 


/NOTYPEAHEAD[=ttnnn: ] 


Disables the typeahead option; the terminal driver does not 
store input characters ina buffer to prevent their loss. 


A nonprivileged user can display all terminals that have the 
typeahead option disabled but can only disable the option 
for TI:. A privileged user can disable typeahead for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have typeahead disabled. 


/VFILL[=ttnnns: ] 


Enables the vertical fill characters option £Or the 
specified terminal. The option instructs the system 
terminal driver to add four fill characters following each 
line feed. 


A nonprivileged user can display all terminals that have the 
vertical fill characters option enabled but can only enable 
the option for TI:. A privileged user can enable the option 
for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the vertical fill characters option 
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SET 


enabled. 
/NOVFILL[=ttnnn: ] 


Disables the vertical fill characters option for the 
Specified terminal. 


A nonprivileged user can display all terminals that have the 
vertical fill characters option disabled but can only 
disable the option for TI:. A privileged user can disable 
the option for any terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the vertical fill characters option 
disabled. 


/WRAP[=ttnnn: ] 


Enables the wrap-around option. The wrap-around option 
instructs the terminal driver to generate a carriage 
return/line feed sequence when the number of input 


characters exceeds the terminal’s buffer size. The carriage 
return/line feed sequence is transparent and does not appear 
in the input buffer. 


A nonprivileged user can display all terminals that have the 
wrap-around option enabled but can only enable the option 
for TI:. A privileged user can enable the option for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the wrap-around option enabled. 


/NOWRAP[=ttnnn: J 


Disables the wrap-around option; the terminal driver does 
not accept input characters beyond the buffer size for the 
terminal. 


A nonprivileged user can display all terminals that have the 
wrap-around option disabled but can only disabled the option 
for TI:. A privileged user can disable the option for any 
terminal. 


When you omit =ttnnn:, the system displays all of the 
terminals that have the wrap-around option disabled. 


TAL 
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TASKLIST - ATL FORMAT (NP) 
The TAL command displays the names and status of all tasks or of 
a specific task installed in the system. The display format is 
the same as that of the ACTIVE TASK LIST (ATL) command. 
Syntax 

TAL [taskname] 


taskname 


The name of a specific task. 


TAS 
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TASKLIST (NP) 
The TASKLIST command displays a description of all or of a 
Specific task installed in the system. The display contains the 
following information: 

1. Task name 

2. Task version identification 

3. Partition name 

4. Task priority 

5. Size of task in bytes (octal) 

6. Load device identification 

7. Disk address logical block number (octal) 

8. Task memory state 
The display lists the tasks installed in primary pool and _ then 
those in secondary pool. 
Syntax 

TASKLIST [TASKNAME][/DEV=ddnnn: ] 

taskname 

The name of a specific task. 
/DEV=ddnnn: 


Displays the names of and status of all tasks installed from 
the specified device. 


If you specify both taskname and /DEV, the system displays 
information about the task installed from that device. 


TIM 
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TIME (NP,P) 


The TIME command allows you to: 


e Set the current time of day (privileged) 
e Set the current date (privileged) 


@ Display the current time and date 


Syntax 


hrs 


mins 


Secs 


mi 


m2 


day 


year 


TIME hrs:mins[:secs]] [M1/day/year] 
or 
[hrs:mins[:secs]] [day-m2-year] 


The value for hours, which can be between 0 and 23. 


The value for minutes, which can be between 0 and 59. 


The value for seconds, which can be between 0 and 59. (The 
value for seconds is an optional parameter.) 


The value for month, specified as a number between 1 and 12. 


The value for the month, specified as a 3 letter 
abbreviation. 


The value for the day of the month, which can be between 1 
and 31. 


The value of the year, which can be between 0 and 99. The 


D-78 


TIM 


year is relative to 1900, so that 1987 is specified as 87. 


Notes: 


When the command specifies neither time nor date, the 
system displays the current time and date on the 
entering terminal. 


If a privileged user specifies the time and date, the 
command sets the clock and calendar. If only the time 
is specified, only the clock is set. If only the date 
is specified, only the calendar is set. 


A privileged user can specify the time and date in 
either order. 


The form to specify the date does not affect the display 
format. The date is always displayed as day-month-year. 


All numeric values are decimal. No terminating period 
1s necessary (or permitted). 


UFD 
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USER FILE DIRECTORY (NP,P) 


The USER FILE DIRECTORY command creates a User File Directory 
(UFD) on a Files-1i1 volume and enters its name into the Master 
File Directory (MFD). 


Before a UFD is created, the device must first be initialized and 
mounted. 


Nonprivileged users can create directories only on those devices 
they are privileged for (for example a nonprivileged user cannot 


create a directory on the device LBO: or LB1:). A privileged 
user can create a directory on any mounted Files-11 volume. 


Syntax 
UFD ddnnn:[dir-spec][/keywords ] 
ddnnn: 


Device and unit containing the volume on which the directory 
being created will reside. 


The default device is the current device assigned the value 
Of ‘SYs. 


[dir-spec] 


Specifies the directory that you want to create. The 
directory name can be of the form [g,m] or [directory]. The 
variables g and m represent the group and member numbers, 
respectively, and their values can _ be between 1 and 377 


(octal). Additionally, the directory can be a name from 1 
to 9 characters in length, consisting of the characters A-Z 
and 0-9. 


There is no default for the directory, you must specify one. 


/NOWARNINGS 


Suppresses error messages that can occur as a result of the 
command. 


/PRO=(system,owner,group,world) 


Establishes access rights for the directory file. 


UFD 


A protection code specifies the type of access to your files 
that you want other users to have. The system recognizes 
four classes of users. The position of the user classes in 
the protection code string is fixed in this’ order: 
[SYSTEM, OWNER, GROUP, WORLD]. The location in the string 
defines which user class you are specifying. 


Access codes consist of four groups of four codes in the 
access rights word, as follows: 


- Read access 
Write access 
Extend access 
- Delete access 


OF = w 
I 


In each instance, the absence of a code means that the user 
class is denied that type of access. 


The parentheses are required syntax. 
The defaults are: (RWE,RWE,R,R) 
/UIC=[g,m] 


Establishes the owner User Identification Code (UIC) for the 
directory file. The variables g and m represent group and 
member numbers, respectively, and can be in the range 1 
through 377 (octal); the square brackets are required 
syntax. 


The default ownership of a directory depends on the device 
on which it is created. If the directory is created on LBO: 
or LB1: ona stand-alone or server system, the UIC is 
(377,0]. If the directory is created on LBO: or LBl: ona 
workstation, the UIC is [377,x], where x is the number 
assigned when the workstation was defined. For any other 
device specification, the directory is owned by the issuer 
of this command. You can specify any UIC as the owner by 
using this qualifier. However, a nonprivileged user cannot 
always create files in a directory that is owned by a 
different UIC. 
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UNBLOCK (NP,P) 

The UNBLOCK command continues the execution of a previously 
blocked active task or allows a previously blocked dormant task 
to execute if it is requested to do so. (See the description of 
the BLOCK command. ) 


Nonprivileged users can unblock any active task running from the 
issuing terminal. A privileged user can unblock any task. 


The system automatically unblocks an active task when it is 
aborted. 


Syntax 


UNBLOCK [taskname][/keyword] 


taskname 
The name of the task. If you omit taskname, the command 
unblocks the task being run from the issuing terminal (task 
Lenn). 


/TERM=ttnnn: 


A privileged keyword that clears the block bit for a task 
being run from the specified terminal. 


UNL 
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UNLOAD (NP) 


The UNLOAD command removes a loadable device driver from memory. 
If a device is mounted, attached, or has outstanding I/O, its 
driver cannot be unloaded. Also, the UNLOAD command cannot 
remove a data base from memory, even if the data base was loaded 
by means of the LOAD command. 


To unload a device driver from memory, the driver’s symbol table 
(STB) file must reside on the system device (LB:) in the 
directory [ZZSYS]. 

Syntax 


UNLOAD dd: 


UNS 
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UNSTOP (NP,P) 
The UNSTOP command continues execution of a task that has’ been 
stopped internally by the Executive. Examples of stopped tasks 


are tasks that have issued a STOPS or RCSTS (RECEIVE DATA OR 
STOP) directive. 


A nonprivileged user can only unstop tasks being run from the 
issuing terminal. A privileged user can unstop any task. 


Syntax 


UNSTOP taskname[/keyword] 


taskname 
The name of the task. If you omit taskname, the command 
unstops the task being run from the issuing terminal (task 
ttnnn). 


/TERM=ttnnn: 


A privileged keyword that clears the stop bit for ae task 
being run from the specified terminal. 


INDEX 


INDEX 


Abbreviated form of DCL commands, 
2-1 
Abbreviations, 2-7 
ABORT, 3-2, D-6 
background processing, 2-15 
definition, 2-16 
ACTIVE, D-/7 
Active task display, 9-8 
ACTIVE TASK LIST, D-14 
Adding lines to file, 11-12 
Adding subroutine to module, 14-7 
Addressing locations in files, 
10-5 
Addressing modes 
ZAP, 10-5 
Alphabetical PRO/Tool Kit DCL 
command descriptions, 3-1 
Alphabetical PRO/Tool Kit MCR 
command descriptions, D-5 
ALTER, D-8 
Altering 
active task display, 9-8 
RMD memory display, 9-7 
task header display, 9-10 
ANALYZE/MEDIA, 3-4 
APPEND, 3-5 


Application 
refer to program development 
cycle 
Applying updates, 14-3 
Arguments 


in DCL command line, 2-2 
-ASK, 4-28 
-ASKN, 4-30 
-ASKS, 4-33 
ASSIGN, 3-9, D-9 
ASSIGN/TASK, 3-13 
Associated documents, xviii 
Attaching terminal in background 

mode 

caution against, 2-16 
Audit trail 

controlling, 11-19 

deleting, 11-23 

length, 11-20 

position, 11-20 

suppressing, 11-22 


value, 11-21 


Background processing, 2-15 

BASIC, 3-14 

-BEGIN, 4-35 

BLOCK, D-1/7 

BREAKPOINT TO EXECUTIVE DEBUGGING 
TOOLBRK 

see BRK. 
BROADCAST, 3-15 


CANCEL, 3-16, D-19 
Cancellation 
of DCL command, 2-9 
Catchall facility 
overview, 5-1 
using, 5-2 
using the TDX task, 5-5 
writing a catchall task, 5-7 
Catchall task 
coding conventions for, 5-7 
TDX, 5-5 
CBD, D-20 
.CHAIN, 4-36 
Change bar format, 6-8 
CLEAR, 3-17 
CLOCK QUEUE 
See CLQ 
-CLOSE, 4-37 
CLO, D-22 
.CMD extension, 4-1 
CMP, 6-1 
change bar format, 6-8 
command format, 6-2 
differences format, 6-7 
invoking, 6-2 
messages, 6-9 
output files, 6-6 
Switches, 6-3 
COBOL, 3-18 
Command 
ABORT, 3-2, D-6 MCR 
ACTIVE, D-7 MCR 
ACTIVE TASK LIST, D-14 MCR 
ALTER, D-8 MCR 
ANALYZE/MEDIA, 3-4 
APPEND, 3-5 
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D-9 MCR 
321.3 


ASSIGN, 3-9, 
ASSIGN/TASK, 
BASIC, 3-14 
BLOCK, D-17 MCR 

BRK, D-18 MCR 
BROADCAST, 3-15 
CANCEL, 3-16, D-19 MCR 
CBD, D-20 MCR 
CLEAR, 3-17 

CLQ, D-22 MCR 
COBOL, 3-18 
CONTINUE, 3-25 
CONVERT, 3-26 
COPY, 3-32 
CREATE, 3-39 
CREATE/DIRECTORY, 
DCL, D-23 MCR 
DEASSIGN, 3-45 
DEBUG, 3-47, D-24 MCR 
DEFINE, 3-48 
DELETE, 3-52 
DELETE/DIRECTORY, 
DEVICES, D-25 MCR 
DFL, D-27 MCR 
DIBOL, 3-56 
DIFFERENCES, 3-60 
DIRECTORY, 3-64 
DISMOUNT, 3-68, 
DUMP, 3-69 

EDIT, 3-74 
EDIT/EDT, 3-74 
EDIT/PROSE, 3-77 
EDIT/SLP, 3-78 
EXIT, 3-81 

FIX, 3-82, D-34 MCR 
FMT, D-36 MCR 

FORMAT, 3-84 

FORTRAN, 3-85 

HELP, 3-91, D-37 MCR 
INITIALIZE, 3-92 
INITVOLUME, D-39 MCR 
INSTALL, 3-94 

LIBRARY, 3-96 
LIBRARY/COMPRESS, 3-97 
LIBRARY/CREATE, 3-99 
LIBRARY/DELETE, 3-102 
LIBRARY/EXTRACT, 3-103 
LIBRARY/INSERT, 3-104 
LIBRARY/LIST, 3-106 
LIBRARY/REMOVE, 3-108 
LIBRARY/REPLACE, 3-109 


3-42 


3=55 


D-32 MCR 
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LINK, 3-111 

LINK/C81, 3-126 

LOAD, 3-129, D-44 MCR 
LUN, D-45 MCR 
MACRO, 3-130 
MAIL, 3-138 
MOUNT, 3-139, 
OPE, D-47 MCR 
PAR, D-50 MCR 
PASCAL, 3-140 
PHONE, 3-143 
PRINT, 3-144 
PRINT/REMOTE, 
PURGE, 3-146 
REASSIGN, D-51 MCR 
REM, D-52 MCR 
REMOVE, 3-149 
RENAME, 3-150 
REPLY, 3-153 
RESUME, D-53 MCR 
RUN, D-54 MCR 

RUN installed task, 
RUN uninstalled task, 
SET, D-58 MCR 
SET DAYTIME, 
SET DEFAULT, 3-160 

SET DEVICE, 3-161 

SET FILE, 3-163 

SET HOST, 3-166 

SET PRIORITY, 3-167 

SET PROMPT, 3-168 

SET PROTECTION, 3-169 
SET PROTECTION/DEFAULT, 
SET 
SET 
SET 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 


D-46 MCR 


3-145 
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TERMINAL, 3-175 

TIME, 3-159 
ASSIGNMENTS, 
CLOCK QUEUE, 
COMMON, 3-182 
DAYTIME, 3-184 
DEFAULT, 3-185 
DEVICES, 3-186 
LOGICALS, 3-187 
MEMORY, 3-188 
PROTECTION, 3-189 
TASK/DYNAMIC, 3-196 
TASK/LOGICAL_UNITS, 
TASKS/ACTIVE, 3-190 


3-180 
3-181 


27195 
SHOW TASKS/INSTALLED, 


PROTECTION/NODEFAULT, 


3-154 
3-157 


3-172 
3-174 


3-199 


TASKS/ACTIVE/DYNAMIC, 


3-194 


SHOW TERMINAL, 3-200 
SHOW TIME, 3-184 
SHOW USERS, 3-202 
SPAWN, 3-203 
START, 3-204 
START/UNBLOCK, 3-205 
STOP/BLOCK, 3-206 
SUBMIT/REMOTE, 3-207 
TAL, D-76 MCR 
TAS, D-7/77 MCR 
TIME, D-78 MCR 
TYPE, 3-208 
UNB, D-82 MCR 
UNL, D-83 MCR 
UNLOAD, 3-211 
UNLOCK, 3-212 
UNS, D-84 MCR 
Command files, 4-1 
Command line 
DCL, 2-1 
Command line continuation, 2-8 
Commands 
file manipulation, 1-2 
manipulating tasks, 1-2 
miscellaneous, 1-3 
program development, 1-2 
SET and SHOW, 1-3 
Comments 
comment character, 2-8 
COMMON BLOCK DIRECTORY 
see CBD. 
Compare utility 
see CMP 
Compatibility 
with RSX command files, 4-93 
Compound tests, 4-25 
CONTINUE, 3-25 
Controlling audit trail, 11-19 
CONVERT, 3-26 
Convert Utility, 12-1 
COPY, 3-32 
Correction file, 14-4 
CREATE, 3-39 
CREATE/DIRECTORY, 3-42 


Creating source files with SLP, 


11-16 
CTRL/C 
definition, 2-16 
foreground processing, 2-15 
CTRL/Z, 2-9 
to cancel DCL command, 2-9 


INDEX 


CVT, 12-1 


.DATA, 4-38 
DCL 
abbreviations, 2-7 
ABORT command use, 2-16 
background processing, 2-15 
colon use, 2-8 
command abbreviations, 2-1 
command format, 2-2 
command line comments, 2-8 
command line continuation, 2-8 
command line errors, 2-9 
command line format, 2-1 
command line terminators, 2-2 
CTRL/C use, 2-16 
customizing, 5-1 
equal sign use, 2-8 
errors, 2-9 
executing the command from MCR, 
D-23 
file specifications, 2-13 
foreground processing, 2-15 
HELP, 2-5 
initialization, 2-10 
Logical name translation, 2-15 
prompting, 2-2 
qualifiers, 2-3 
Single Line Editor, 2-11 
termination, 2-10 
wildcard features in, 2-13 
Del 
functional groups, 1-1 
DCLSCOMMAND_OPTIONS 
control list for; 5=2 
defining tor Catchall facility, 
5-2 
defining the logical name 
‘format for, 5-3 
keywords in, 5-3 


DCLSCOMMANDOPTIONS 
specifying as a logical for MCR, 
D-1 
DEASSIGN, 3-45 
DEB 
See DEBUG. 
DEBUG, 3-47, D-24 
-DEC, 4-39 


Default file type, 4-1 
DEFINE, 3-48 
Define logical EOF, 4-27 
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INDEX 


DEFINE LOGICALS 
see DFL 
-DELAY, 4-40 
DELETE, 3-52 
DELETE/DIRECTORY, 3-55 
Deleting file marked for delete, 
15-10 
Deleting lines from file, 11-14 
Deletion of multiple-allocated 
blocks, 15-10 
DEV 
see DEVICES 
Development of the application, 
XV1 
Device and file manipulation, 1-1 
Also see Chapter 3. 
DEVICES, D-25 
DFL, D-27 
DIBOL, 3-56 
DIFFERENCES, 3-60 
Differences format, 6-7 
DIGITAL COMMAND LANGUAGE 
see DCL. 
DIRECTORY, 3-64 
Directory validation, 15-4 
.DISABLE, 4-41 
DISMOUNT, 3-68, D-32 


DMO 
see DISMOUNT. 
DMP, 7-1 


command format, 7-2 
error messages, /-11 
examples, 7-8 
header dump, 7-10 
invoking, 7-2 
multiple format dump, 7-8 
record dump, 7-9 
Switches, 7-3 
DO 
command line terminator, 2-2 
Document conventions, xviil 
Document structure, xvl 
DUMP, 3-69 


EDIT, 3-74 
EDIT/EDT, 3-74 
see EDT 
EDIT/PROSE, 3-77 
EDIT/SLP, 3-78 
Editor 
defining DCLSEDITOR, 5-10 


specifying the default, 5-10 
Editors 
text,. 1=5 
EDT command file 
directory location, 3-74 
use with /COMMAND qualifier, 
3-74 
Effect of qualifier position in 
command line, 2-4 
~ENABLE, 4-42 
-END, 4-46 
Entry point table, 8-3 
~ERASE, 4-47 
Error 
detection by system, 2-9 
Error messages 
indirect, 4-95 
Errors 
DCL Command Line, 2-9 
JEXIT; 42249 
EXIT, 3-81 
disabling the command, 5-11 
ExX14 | 
from PRO/Tool Kit, 2-10 
Expressions, 4-16, 4-18 


File Compare Utility, 6-1 
File contents determination, 14-8 
File contents validation, 14-8 
File Dump Utility, 7-1 
File manipulation commands, 1-2 
File specifications, 2-13 
File Structure Verification 
Utility, Lost 
Files marked for delete, 15-9 
/FINAL qualifier 
with ASSIGN, 3-10 
with DEFINE, 3-49 
FIX, 3-82, D-34 
FIX-IN-MEMORY 
See FIX 
Flying installs 
definition of, 5-14 
FMT, D-36 
Foreground processing, 2-15 
-FORM, 4-50 
FORMAT, 3-84 
See FMT. 
Format 
PIP commands, 13-2 
Format of library files, 8-2 
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Formats of CMP output files, 

FORTRAN, 3-85 

/FR, 15-5 

FREE command, 9-7 

Functional groups 

dcl commands, 1-1 

functions initiated by DCL 

commands, A-1 


6-6 


general error messages, B-1 
.GOSUB, 4-56 
.GOTO, 4-57 
Header dump, 7-10 
HEL 

see HELP 
HELP, 2-5, 3-91, D-37 

aS a separate command, 2-5 

while using a DCL command, 
Hyphen 

in command line, 


2-5 
2-8 
I/O error messages, B-20 
~IF, 4-25, 4-58 
IFACT, 4-60 
IFDF, 4-61 
.-IFDISABLED, 
. [FENABLED, 
~IFF, 4-65 
-IFINS, 4-62 
.IFLOA, 4-64 
.-IFNACT, 4-60 
-IFNDF, 4-61 
.IFNINS, 4-62 
.IFNLOA, 4-64 
~IFT, 4-65 
.INC, 4-66 
Indirect 
-ASK, 
-ASKN, 
-ASKS, 
-BEGIN, 
.CHAIN, 4-36 
.CLOSE, 4-37 
command files, 4-1 
command processor, 
.DATA, 4-38 
.DEC, 4-39 
Define logical EOF, 
.DELAY, 4-40 
directive summary, 


4-63 
4-63 


4-28 

4-30 

4-33 
4-35 


4-2 


4-27 


4-4 
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.DISABLE, 4-41 
-ENABLE, 4-42 
»-END, 4-46 
»-ERASE, 4-4/7 
error messages, 
~.EXIT, 4-49 
expressions, 
~FORM, 4-50 
.GOSUB, 4-56 
.GOTO, 4-57 
~IF, 4-25, 4-58 
.IFACT, 4-60 
.IFDF, 4-61 
.IFDISABLED, 
. IFENABLED, 
.IFF, 4-65 
~IFINS, 4-62 
.IFLOA, 4-64 
.IFNDF, 4-61 
-IFNINS, 4-62 
.IFNLOA, 4-64 
-IFT, 4-65 
-INC, 4-66 


4-95 


4-16, 


4-63 
4-63 


4-18 


information only messages, 


»~LABEL, 4-67 
messages, 4-94 
numberic symbols, 
.ONERR, 4-68 
-OPEN, 4-69 
-OPENA, 4-70 
~OPENR, 4-71 
.PARSE, 4-72 
»~PAUSE, 4-73 
»~READ, 4-74 
reserved symbols, 
~RETURN, 4-76 
RSX compatibilty, 
~.SETD, 4-79 
~SETF, 4-77 
~SETL, 4-77 
.SETN, 4-78 
~SETO, 4-79 
.SETS, 4-80 
~SETT, 4-77 
special symbols, 
logical, 4-9 
numeric, 4-11 
String, 4-14 
.STOP, 4-82 
string symbols, 4-18 
substitution format, 


4-9 


4-16 


4-19 


4-93 


4-20 
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substrings, 4-18 combining library functions, 
Switches, 4-21 8-42 
symbol substition, 4-19 compress switch, 8-15 
symbols, 4-8 /CR, 8-16 
TEST, 4-83 create switch, 8-16 
-TESTDEVICE, 4-85 /DE, 8-18 
-TESTFILE, 4-86 default switch, 8-19 
-TESTPARTITION, 4-87 delete global switch, 8-21 
-TESTSYSTEM, 4-88 delete switch, 8-18 
. TRANSLATE, 4-90 /DF, 8-19 
using directives, 4-24 /DG, 8-21 
WAIT, 4-91 entry point switch, 8-23 
-XOT, 4-92 entry point table, 8-3 
Indirect Command Processor JEP, 8-23 
refer to Chapter 4 error messages, 8-43, 8-44 
use with PRO/Tool Kit DCL J/EX, 8-25 
commands, 2-1 extract switch, 8-25 
Indirect command processor, 4-1 fatal errors, 8-44 
INI file specifier defaults, 8-11 
See INITVOLUME /FU, 8-29 
INITIALIZE, 3-92 JIN, 8-26, 8-27 
INITVOLUME, D-39 insert switch, 8-26, 8-27 
Input file wildcards, 13-11 invoking, 8-11 
INSTALL, 3-94 /LE, 8-29 
Installation of application, xvi ful, 8-29 
Intended audience, xvi library file format, 8-2 
Interactive library header, 8-2 
program development, 1-1 list switches, 8-29 
program execution and control, ZMH - -8=30 
1-1 modify header switch, 8-30 
Interactive use of PRO/Tool Kit module header, 8-3 
DCL, 2-1 module name table, 8-3 
Invoking replace switch, 8-31, 8-37 
CMP, 6-2 restrictions, 8-10 
CVT, 12-1 /RP, 8-31, 8-37 
DMP, 7-2 selective search switch, 8-39 
LBR, 8-11 Squeeze switch, 8-40 
PAT, 14-2 /SS, 8-39 
PIP, 13-1 Switches, 8-13 
RMD, 9-2 /SZ, 8-40 
SLP, 11-2 /ul, 15-6 
VFY, 15-1 Librarian Utility Program, 8-1 
ZAP, 10-7 LIBRARY, 3-96 


Library header, 8-2 
LIBRARY/COMPRESS, 3-97 


.LABEL, 4-67 LIBRARY/CREATE, 3-99 
LB:[{1,2]EDTSYS.EDT LIBRARY/DELETE, 3-102 
see EDT use with /COMMAND LIBRARY/EXTRACT, 3-103 
qualifier LIBRARY/INSERT, 3-104 
LBR, 8-1 LIBRARY/LIST, 3-106 
/CO, 8-15 LIBRARY/REMOVE, 3-108 
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LIBRARY/REPLACE, 3-109 
LINK, 3-111 
LINK/C81, 3-126 
/LO, 15-6 
LOA 

see LOAD 
LOAD, 3-129, D-44 
Locations 

addressing 

in files, 10-5 

/LOG qualifier 

with PRINT/REMOTE, 3-145 
Logical name translation, 2-15 
LOGICAL UNIT NUMBERS 

see LUN 
Lost block recovery, 15-10 
LUN, D-45 


MACRO, 3-130 

MAIL, 3-138 

Manual objectives, xvi 

MCR 

basic concepts, D-1 
Command 

ABORT, D-6 
ACTIVE, D-/7 
ACTIVE TASK LIST, D-14 
ALTER, D-8 
ASSIGN, D-9 
BLOCK, D-17 
CANCEL, D-19 
CBD, D-20 
CLQ, D-22 
DCL, D-23 
DEBUG, D-24 
DEVICES, D-25 
DFL, D-27 
DISMOUNT, D-32 
EXIT, D-33 
FIX, D-34 
FMT, D-36 
HELP, D-37 
INITVOLUME, D-39 
LOAD, D-44 
LUN, D-45 
MOUNT, D-46 
OPE, D-47 
PAR, D-50 
REASSIGN, D-51 
REM, D-52 
RESUME, D-53 
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RUN, D-54 
SET, D-58 
TAL, D-76 
TAS, D-77 
TIME, D-78 
UFD, D-80 
UNB, D-82 
UNL, D-83 
UNS, D-84 
command 
BRK, D-18 


command line, D-1 
comments in, D-4 
correcting mistakes in, D-3 
keywords in, D-4 
prompting in, D-2 
command processing, D-5 
privileged and nonprivileged 
users, D-l1 
Specifying the logical 
DCLSCOMMANDOPTIONS for, D-1 
Miscellaneous commands, 1-3 
Module name table, 8-3 
Monitor Console Routine 
See MCR 
MOU 
See MOUNT 
MOUNT, 3-139, D-46 
Multiple format dump, 7-8 


Nesting command files, 4-1 
/NOWARNINGS qualifier 

with PRINT/REMOTE, 3-145 
Numeric symbols, 4-16 


Object Module Patch Utility, 14-1 
Object modules, 14-5 
~ONERR, 4-68 
OPE, D-4/7 
OPEN, 4-69 
-OPENA, 4-70 
~OPENR, 4-71 
OPENREGISTER 
see OPE 
Output file wildcards, 13-10 
Overlaying lines, 14-5 
OWNER command, 9-9 


PAR, D-50 
Parameters 
in DCL command line, 2-2 
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~PARSE, 4-72 
PARTITION DEFINITIONS 


See PAR 


PASCAL, 3-140 
PAT, 14-1 


adding subroutine, 14-7 

applying updates, 14-3 

command line errors, 14-10 

command line format, 14-2 

correction file, 14-4 

errors in file contents, 14-15 

errors in file format, 14-15 

file contents determination, 
14-8 

file contents validation, 14-8 

file specification errors, 
14-11 

I/O errors, 14-13 

information messages, 14-10 

input file, 14-4 

internal software error, 14-16 

invoking, 14-2 

messages, 14-9 

module, 14-5, 14-7 

object modules, 14-5 

overlaying lines, 14-5 

storage allocation error, 14-17 

updates, 14-3 

updating object modules, 14-5 

validation, 14-8 


.PAUSE, 4-73 
Peripheral Interchange Program, 


13-1 


PHONE, 3-143 
PIP, 13-1 
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See REASSIGN 
.READ, 4-74 
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Record dump, 7-9 
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see REMOVE 
REMOVE, 3-149, D-52 
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DEFAULT, 3-185 
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FILE, 3-163 

HOST, 3-166 
PRIORITY, 3-167 
PROMPT, 3-168 
PROTECTION, 3-169 
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E 
see DCL Single Line Editor 
P, 11-1 
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Symbol value substitution, 4-19 
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see TIME 
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UNL 
see UNLOAD 
UNLOAD, 3-211 
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regular task image, 10-3 

relocation bias, 10-5 

relocation register, 10-14 
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